= kitty-diff - A side-by-side diff tool with syntax highlighting and images
:toc:
:toc-placement!:


== Major Features

* Displays diffs side-by-side in the kitty terminal.

* Does syntax highlighting of displayed diffs

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

* Does recursive directory diffing


image::../../screenshots/diff.png?raw=true[Screenshot, showing a sample diff]

toc::[]


== Installation

Simply install link:https://github.com/kovidgoyal/kitty[kitty].  You also need
to have either the link:https://git-scm.com/[git] program or the `diff` program
installed. Additionally, for syntax highlighting to work,
link:http://pygments.org/[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:

```sh
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`
|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 change | `n`
|Scroll to previous change | `p`

|Increase lines of context | `+`
|Decrease lines of context | `-`
|All lines of context      | `a`
|Restore context to default| `=`

|===

[options="header"]


== Configuring kitty-diff

You can configure the colors used, the diff implementation, the default lines of context, etc.
by creating a diff.conf in your kitty config folder. See the link:diff.conf[default diff.conf]
for details.


== Integrating with git

Add the following to `~/.gitconfig`:

```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
link:https://github.com/kovidgoyal/kitty/blob/master/protocol-extensions.asciidoc[kitty
only], such as the
link:https://github.com/kovidgoyal/kitty/blob/master/graphics-protocol.asciidoc[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 :)