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¶

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¶

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 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 3

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

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 \x20\x20\x20\x20

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

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¶

color_scheme auto

Whether to use the light or dark colors. The default of auto means to follow the parent terminal color scheme.

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. This sets the colors used for light color schemes, use dark_pygments_style to change the colors for dark color schemes.

dark_pygments_style github-dark

The pygments color scheme to use for syntax highlighting with dark colors. 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. This sets the colors used for dark color schemes, use pygments_style to change the colors for light color schemes.

foreground black

Basic colors

dark_foreground #f8f8f2
background      white
dark_background #212830

Basic colors

title_fg      black
dark_title_fg white
title_bg      white
dark_title_bg #212830

Title colors

margin_bg      #fafbfc
dark_margin_bg #212830
margin_fg      #aaaaaa
dark_margin_fg #aaaaaa

Margin colors

removed_bg                #ffeef0
dark_removed_bg           #352c33
highlight_removed_bg      #fdb8c0
dark_highlight_removed_bg #5c3539
removed_margin_bg         #ffdce0
dark_removed_margin_bg    #5c3539

Removed text backgrounds

added_bg                #e6ffed
dark_added_bg           #263834
highlight_added_bg      #acf2bd
dark_highlight_added_bg #31503d
added_margin_bg         #cdffd8
dark_added_margin_bg    #31503d

Added text backgrounds

filler_bg      #fafbfc
dark_filler_bg #262c36

Filler (empty) line background

margin_filler_bg      none
dark_margin_filler_bg none

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

hunk_margin_bg      #dbedff
dark_hunk_margin_bg #0c2d6b
hunk_bg             #f1f8ff
dark_hunk_bg        #253142

Hunk header colors

search_bg      #444
dark_search_bg #2c599c
search_fg      white
dark_search_fg white
select_bg      #b4d5fe
dark_select_bg #2c599c
select_fg      black
dark_select_fg white

Highlighting

Keyboard shortcuts¶

map q quit
map esc quit

map j scroll_by 1
map down scroll_by 1

map k scroll_by -1
map up scroll_by -1

map home scroll_to start

map end scroll_to end

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

map page_up scroll_to prev-page

map n scroll_to next-change

map p scroll_to prev-change

map shift+j scroll_to next-file

map shift+k scroll_to prev-file

map a change_context all

map = change_context default

map + change_context 5

map - change_context -5

map / start_search regex forward

map ? start_search regex backward

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

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

map f start_search substring forward

map b start_search substring backward

map y copy_to_clipboard

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.

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¶

2025, Kovid Goyal