= 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"]
== 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 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 :)
