kitten-diff(1)

📦
version 0.49.2 · 12 versions
, in arch rolling, nixpkgs unstable

💖 Name 💖

okay so this is kitten-diff(1) from the kitty crew, and it’s literally the pretty, side-by-side diffing tool for files and images. It’s a fast side-by-side diff tool with syntax highlighting and images, and it’s giving main character energy in your terminal 💅.

🌈 Major features 🌈

  • Displays diffs side-by-side in the kitty terminal.
  • Does syntax highlighting of the displayed diffs, asynchronously, for maximum speed. Asynchronous slay ✨.
  • Displays images as well as text diffs, even over SSH. Obsessed.
  • Does recursive directory diffing. There’s a screenshot showing a sample diff (images not supported).

💅 Installation 💅

Simply install kitty — the quickstart section is your bestie here 💖.

🚀 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. Directory diffing? She ate 🍓.

🎮 Keyboard controls 🎮

These are the keys that run the diff view, bestie. No cap, they’re all here:

  • Quit — Q
  • 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, Ctrl+F
  • Scroll to previous page — PgUp, Ctrl+B
  • Scroll down half page — Ctrl+D
  • Scroll up half page — Ctrl+U
  • 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 or exit — 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.

Alternatively, git-kitten-diff (over at https://github.com/eureka-cpu/kitty-diff-git) is a git plugin that forwards git diff arguments to kitty-diff without needing any ~/.gitconfig changes. Once installed, simply run:

git kitten diff

💀 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. It’s giving customizable queen energy 👑.

🦋 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

mark_moved_lines

mark_moved_lines yes

Highlight lines that are moved, that is removed from the left and added to the right differently, using the moved_bg color.

word_diff_mode

word_diff_mode words

The algorithm to use for highlighting which parts of changed lines differ. When set to words, changed words in each changed line are highlighted. When set to central, the central changed region of each changed line is highlighted at the byte level. The words mode is generally more useful as it shows exactly which words changed. Note that the words mode only applies when a changed chunk has equal numbers of added and removed lines.

word_regex

word_regex [^\s\p{P}]+

The regular expression used to define a word when word_diff_mode is words. The default value matches any run of non-whitespace and non-punctuation characters. The expression must be a valid Go regular expression. If an invalid expression is provided, diff will fail with an error.

sticky_header yes

When scrolled past the header of a file, keep the file’s name and separator pinned to the top of the screen.

🌈 COLORS 🌈

Okay bestie, this is the part where you make your diff actually pretty. Every setting here comes in a light flavor and a dark_ flavor, and honestly? It's giving custom aesthetic on main. 💅

🎀 color_scheme

color_scheme auto

Whether you're living in light mode or dark mode. The default, auto, means it follows whatever your parent terminal is doing. Heads up though: the actual colors used for dark schemes are set by all the dark_* settings down below, and the non-prefixed settings are the ones used for light colors. So don't get it twisted 💖

✨ pygments_style

pygments_style default

The pygments color scheme used for syntax highlighting. Peep the pygments builtin styles at https://pygments.org/styles/ for the full menu of schemes. Important: this does not change the colors used for diffing, only the colors used for syntax highlighting — for the general colors, use the settings below. And this one sets the colors for light color schemes, so use dark_pygments_style if you want the dark ones. 🦋

🌙 dark_pygments_style

dark_pygments_style github-dark

Same deal as above but for dark colors: the pygments color scheme used for syntax highlighting when you're in dark mode. Again, the styles live at https://pygments.org/styles/. Again, this does not change the colors used for diffing, only the colors used for syntax highlighting — general colors are the settings below. This sets the colors used for dark color schemes, and you'd use pygments_style to change the colors for light color schemes. Balance, bestie ⭐

💜 foreground, dark_foreground, background, dark_background

foreground      black
dark_foreground #f8f8f2
background      white
dark_background #212830

Basic colors ✨

👑 title_fg, dark_title_fg, title_bg, dark_title_bg

title_fg      black
dark_title_fg white
title_bg      white
dark_title_bg #212830

Title colors — the main character of your diff view, fr.

🌸 margin_bg, dark_margin_bg, margin_fg, dark_margin_fg

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

Margin colors — the cute little gutter zone.

🍓 removed_bg, dark_removed_bg, highlight_removed_bg, dark_highlight_removed_bg, removed_margin_bg, dark_removed_margin_bg

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 — the "oop, that's gone" palette 😭

🧚 added_bg, dark_added_bg, highlight_added_bg, dark_highlight_added_bg, added_margin_bg, dark_added_margin_bg

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 — new stuff, slay 🌱

🦋 moved_bg, dark_moved_bg, moved_margin_bg, dark_moved_margin_bg

moved_bg             #fffde7
dark_moved_bg        #003333
moved_margin_bg      #fff3b0
dark_moved_margin_bg #00495b

Moved text backgrounds — that's for the same text that was removed in one place and added in another. The glow-up relocation 💫

🎀 filler_bg, dark_filler_bg

filler_bg      #fafbfc
dark_filler_bg #262c36

Filler (empty) line background — for the blank spacer lines, keeping the vibe consistent.

💖 margin_filler_bg, dark_margin_filler_bg

margin_filler_bg      none
dark_margin_filler_bg none

Filler (empty) line background in margins — and it defaults to the filler background if you don't set it. iykyk.

🔥 hunk_margin_bg, dark_hunk_margin_bg, hunk_bg, dark_hunk_bg

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

Hunk header colors — the headers ate, no cap.

⭐ search_bg, dark_search_bg, search_fg, dark_search_fg, select_bg, dark_select_bg, select_fg, dark_select_fg

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 — for search matches and your selections, because you gotta see what you're picking 💅

⌨️ KEYBOARD SHORTCUTS ⌨️

Every single one of these is a map line, and bestie, they are all editable. Here's the whole roster. 🫶

🚪 Quit

map --allow-fallback=shifted,ascii q quit
map esc quit

⬇️ Scroll down

map --allow-fallback=shifted,ascii j scroll_by 1
map down scroll_by 1

⬆️ Scroll up

map --allow-fallback=shifted,ascii 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
map --allow-fallback=shifted,ascii ctrl+f scroll_to next-page

📃 Scroll to previous page

map page_up scroll_to prev-page
map --allow-fallback=shifted,ascii ctrl+b scroll_to prev-page

🌗 Scroll down half page

map --allow-fallback=shifted,ascii ctrl+d scroll_to next-half-page

🌓 Scroll up half page

map --allow-fallback=shifted,ascii ctrl+u scroll_to prev-half-page

🔍 Scroll to next change

map --allow-fallback=shifted,ascii n scroll_to next-change

🔎 Scroll to previous change

map --allow-fallback=shifted,ascii p scroll_to prev-change

📁 Scroll to next file

map --allow-fallback=shifted,ascii shift+j scroll_to next-file

📂 Scroll to previous file

map --allow-fallback=shifted,ascii shift+k scroll_to prev-file

👀 Show all context

map --allow-fallback=shifted,ascii 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 --allow-fallback=shifted,ascii f start_search substring forward

🔡 Search backward (no regex)

map --allow-fallback=shifted,ascii b start_search substring backward

📋 Copy selection to clipboard

map --allow-fallback=shifted,ascii y copy_to_clipboard

🚪📋 Copy selection to clipboard or exit if no selection is present

map --allow-fallback=shifted,ascii ctrl+c copy_to_clipboard_or_exit

💻 SOURCE CODE FOR DIFF 💻

The source code for this kitten is available on GitHub at https://github.com/kovidgoyal/kitty/tree/master/kittens/diff. Go poke around, bestie, it's iconic ✨

🖥️ 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. And here's the fun part: you can also use ssh:hostname:remote-file-path to diff remote files. Remote diffing? Obsessed. 🌈

⚙️ 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. Basically a starter pack for your config era 💖

👑 AUTHOR 👑

Kovid Goyal

2026, Kovid Goyal

And that's a wrap, bestie! 🎀 This page is from kitten-diff(1), version 0.49.2, dated Oct 01, 2026 — go forth and diff beautifully, you absolute icon 🦋💜

📦 where this page comes from