kitten-diff(1)

Name
kitten-diff - Pretty, side-by-side diffing of files and images

A fast side-by-side diff tool with syntax highlighting and images

Major features

•   Displays diffs side-by-side in the kitty terminal

•   Does syntax highlighting of the displayed diffs, asynchronously, for maximum speed

•   Displays images as well as text diffs, even over SSH

•   Does recursive directory diffing Screenshot, showing a sample diff (images not supported)

Installation

Simply install kitty.

Usage

In the kitty terminal, run:

    kitten diff file1 file2

to see the diff between file1 and file2.

Create an alias in your shell's startup file to shorten the command, for example:

    alias d="kitten diff"

Now all you need to do to diff two files is:

    d file1 file2

You can also pass directories instead of files to see the recursive diff of the directory contents.

Keyboard controls
Action | Shortcut
Quit | Q, Esc
Scroll line up | K, Up
Scroll line down | J, Down
Scroll page up | PgUp
Scroll page down | PgDn
Scroll to top | Home
Scroll to bottom | End
Scroll to next page | Space, PgDn
Scroll to previous page | PgUp
Scroll to next change | N
Scroll to previous change | P
Increase lines of context | +
Decrease lines of context | -
All lines of context | A
Restore default context |
Search forwards | /
Search backwards | ?
Clear search | Esc
Scroll to next match | >, .
Scroll to previous match | <, ,
Copy selection to clipboard | y
Copy selection or exit | Ctrl+C

Integrating with git

Add the following to ~/.gitconfig:

    [diff]
        tool = kitty
        guitool = kitty.gui
    [difftool]
        prompt = false
        trustExitCode = true
    [difftool "kitty"]
        cmd = kitten diff $LOCAL $REMOTE
    [difftool "kitty.gui"]
        cmd = kitten diff $LOCAL $REMOTE

Now to use kitty-diff to view git diffs, you can simply do:

    git difftool --no-symlinks --dir-diff

Once again, creating an alias for this command is useful.

Why does this work only in kitty?

The diff kitten makes use of various features that are kitty only, such as the kitty graphics protocol, the extended keyboard protocol, etc. It also leverages terminal program infrastructure I created for all of kitty's other kittens to reduce the amount of code needed (the entire implementation is under 3000 lines of code).

And fundamentally, it's kitty only because I wrote it for myself, and I am highly unlikely to use any other terminals :)

Configuration

You can configure the colors used, keyboard shortcuts, the diff implementation, the default lines of context, etc. by creating a diff.conf file in your kitty config folder. See below for the supported configuration directives.

Diffing

syntax_aliases

        syntax_aliases pyj:py pyi:py recipe:py

    File extension aliases for syntax highlight. For example, to syntax highlight file.xyz as file.abc use a setting of xyz:abc. Multiple aliases must be separated by spaces.

num_context_lines

        num_context_lines 3

    The number of lines of context to show around each change.

diff_cmd

        diff_cmd auto

    The diff command to use. Must contain the placeholder _CONTEXT_ which will be replaced by the number of lines of context. A few special values are allowed: auto will automatically pick an available diff implementation. builtin will use the anchored diff algorithm from the Go standard library. git will use the git command to do the diffing. diff will use the diff command to do the diffing.

replace_tab_by

        replace_tab_by \x20\x20\x20\x20

    The string to replace tabs with. Default is to use four spaces.

ignore_name

    A glob pattern that is matched against only the filename of files and directories. Matching files and directories are ignored when scanning the filesystem to look for files to diff. Can be specified multiple times to use multiple patterns. For example:

        ignore_name .git
        ignore_name *~
        ignore_name *.pyc

Colors

pygments_style

        pygments_style default

    The pygments color scheme to use for syntax highlighting. See pygments builtin styles for a list of schemes. Note that this does not change the colors used for diffing, only the colors used for syntax highlighting. To change the general colors use the settings below.

foreground, background

        foreground black
        background white

    Basic colors

title_fg, title_bg

        title_fg black
        title_bg white

    Title colors

margin_bg, margin_fg

        margin_bg #fafbfc
        margin_fg #aaaaaa

    Margin colors

removed_bg, highlight_removed_bg, removed_margin_bg

        removed_bg           #ffeef0
        highlight_removed_bg #fdb8c0
        removed_margin_bg    #ffdce0

    Removed text backgrounds

added_bg, highlight_added_bg, added_margin_bg

        added_bg           #e6ffed
        highlight_added_bg #acf2bd
        added_margin_bg    #cdffd8

    Added text backgrounds

filler_bg

        filler_bg #fafbfc

    Filler (empty) line background

margin_filler_bg

        margin_filler_bg none

    Filler (empty) line background in margins, defaults to the filler background

hunk_margin_bg, hunk_bg

        hunk_margin_bg #dbedff
        hunk_bg        #f1f8ff

    Hunk header colors

search_bg, search_fg, select_bg, select_fg

        search_bg #444
        search_fg white
        select_bg #b4d5fe
        select_fg black

    Highlighting

Keyboard shortcuts

Quit

        map q quit
        map esc quit

Scroll down

        map j scroll_by 1
        map down scroll_by 1

Scroll up

        map k scroll_by -1
        map up scroll_by -1

Scroll to top

        map home scroll_to start

Scroll to bottom

        map end scroll_to end

Scroll to next page

        map page_down scroll_to next-page
        map space scroll_to next-page

Scroll to previous page

        map page_up scroll_to prev-page

Scroll to next change

        map n scroll_to next-change

Scroll to previous change

        map p scroll_to prev-change

Scroll to next file

        map shift+j scroll_to next-file

Scroll to previous file

        map shift+k scroll_to prev-file

Show all context

        map a change_context all

Show default context

        map = change_context default

Increase context

        map + change_context 5

Decrease context

        map - change_context -5

Search forward

        map / start_search regex forward

Search backward

        map ? start_search regex backward

Scroll to next search match

        map . scroll_to next-match
        map > scroll_to next-match

Scroll to previous search match

        map , scroll_to prev-match
        map < scroll_to prev-match

Search forward (no regex)

        map f start_search substring forward

Search backward (no regex)

        map b start_search substring backward

Copy selection to clipboard

        map y copy_to_clipboard

Copy selection to clipboard or exit if no selection is present

        map ctrl+c copy_to_clipboard_or_exit

Source code for diff

The source code for this kitten is available on GitHub.

Command line interface

    kitten diff [options] file_or_directory_left file_or_directory_right

Show a side-by-side diff of the specified files/directories. You can also use ssh:hostname:remote-file-path to diff remote files.

  Options

--context <CONTEXT>
    Number of lines of context to show between changes. Negative values use the number set in diff.conf. Default: -1

--config <CONFIG>
    Specify a path to the configuration file(s) to use. All configuration files are merged onto the builtin diff.conf, overriding the builtin values. This option can be specified multiple times to read multiple configuration files in sequence, which are merged. Use the special value NONE to not load any config file.

    If this option is not specified, config files are searched for in the order: $XDG_CONFIG_HOME/kitty/diff.conf, ~/.config/kitty/diff.conf, $XDG_CONFIG_DIRS/kitty/diff.conf. The first one that exists is used as the config file.

    If the environment variable KITTY_CONFIG_DIRECTORY is specified, that directory is always used and the above searching does not happen.

    If /etc/xdg/kitty/diff.conf exists, it is merged before (i.e. with lower priority) than any user config files. It can be used to specify system-wide defaults for all users. You can use either - or /dev/stdin to read the config from STDIN.

--override <OVERRIDE>, -o <OVERRIDE>
    Override individual configuration options, can be specified multiple times. Syntax: name=value. For example: -o background=gray

Sample diff.conf

You can download a sample diff.conf file with all default settings and comments describing each setting by clicking: sample diff.conf.

Author
Kovid Goyal

Copyright
2024, Kovid Goyal