# kitty-diff - 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

Contents

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

  - Major Features

  - Installation

  - Usage

  - Keyboard controls

  - Integrating with git

  - Why does this work only in kitty?

  - Configuration

    - Diffing

    - Colors

    - Keyboard shortcuts

  - Command Line Interface

    - Options

  - Sample diff.conf

## Installation

Simply install kitty. You also need to have either the git program or the `diff` program installed. Additionally, for syntax highlighting to work, pygments must be installed (note that pygments is included in the macOS kitty app).

## Usage

In the kitty terminal, run:

    kitty +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="kitty +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,` `Ctrl`+`c,` `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 | ``<,` `,``

## Integrating with git

Add the following to ~/.gitconfig:

    [diff]
        tool = kitty
        guitool = kitty.gui
    [difftool]
        prompt = false
        trustExitCode = true
    [difftool "kitty"]
        cmd = kitty +kitten diff $LOCAL $REMOTE
    [difftool "kitty.gui"]
        cmd = kitty kitty +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 2000 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`

`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. The default is to search the system for either git or diff and use that, if found.

`replace_tab_by`

    replace_tab_by \x20\x20\x20\x20

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

### Colors

`pygments_style`

    pygments_style default

The pygments color scheme to use for syntax highlighting. See pygments colors schemes for a list of schemes.

`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

`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

## Command Line Interface

    kitty +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 a 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.

`--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`.