delta - a viewer for diffs with syntax highlighting

Words: technetium - - 20:50 16-10-2020

Code evolves, and we all spend time studying diffs. Delta aims to make this both efficient and enjoyable: it allows you to make extensive changes to the layout and styling of diffs, as well as allowing you to stay arbitrarily close to the default git/diff output.

The most convenient way to configure delta is with a [delta] section in ~/.gitconfig. Here's a quick example:

To quickly change delta configuration on-the-fly, use the git config --global command. For example

Here's what git show can look like with git configured to use delta:

By default, delta restructures the git output slightly to make the hunk markers human-readable:

All the syntax-highlighting color themes that are available with bat are available with delta:

In addition, delta handles traditional unified diff output.

You can download an executable for your system: Linux | MacOS | Windows | All

Alternatively, delta is available in the following package managers:

Set delta to be git's pager in your .gitconfig. Delta has many options to alter colors and other details of the output. An example is

Note that delta color argument values in ~/.gitconfig should be in double quotes, like --minus-color="#340001". For theme names and other values, do not use quotes as they will be passed on to delta, like theme = Monokai Extended.

All git commands that display diff output should now display syntax-highlighted output. For example:

For Mercurial, you can add delta, with its command line options, to the [pager] section of .hgrc.

Delta also handles unified diff output, and can be used as an alternative way of invoking diff -u. The following two commands do the same thing:

All options that have a name like --*-style work in the same way. It is very similar to how

colors/styles are specified in a gitconfig file:

That means: For removed lines, set the foreground (text) color to 'red', make it bold and underlined, and set the background color to #ffeeee.

For full details, see the STYLES section in delta --help .

The numbers are displayed in two columns and there are several configuration options: see the LINE NUMBERS section in delta --help for details, and see the next section for an example of configuring line numbers.

By default, side-by-side view has line-numbers activated, and has syntax highlighting in both the left and right panels: [config]

To disable the line numbers in side-by-side view, but keep a vertical delimiter line between the left and right panels, use the line-numbers format options. For example:

Wide lines in the left or right panel are currently truncated. If the truncation is a problem, one approach is to set the width of Delta's output to be larger than your terminal (e.g. delta --width 250) and ensure that less doesn't wrap long lines (e.g. export LESS=-RS); then one can scroll right to view the full content. (Another approach is to decrease font size in your terminal.)

All delta options can go under the [delta] section in your git config file. However, you can also use named "features" to keep things organized: these are sections in git config like [delta "my-feature"]. Here's an example using two custom features:

Use --diff-highlight or --diff-so-fancy to activate the respective emulation mode.

You may want to know which delta configuration values the emulation mode has selected, so that you can adjust them. To do that, use e.g. delta --diff-so-fancy --show-config:

diff-highlight is a perl script distributed with git that allows within-line edits to be identified and highlighted according to colors specified in git config. diff-so-fancy builds on diff-highlight, making various additional improvements to the default git diff output. Both tools provide very helpful ways of viewing diffs, and so delta provides emulation modes for both of them.

The within-line highlighting rules employed by diff-highlight (and therefore by diff-so-fancy) are deliberately simpler than Delta's Levenshtein-type edit inference algorithm (see discussion in the diff-highlight README). diff-highlight's rules could be added to delta as an alternative highlighting algorithm, but that hasn't been done yet.

Recent versions of Git (≥ v2.17, April 2018) are able to detect moved blocks of code and style them differently from the usual removed/added lines. If you have activated this feature in Git, then Delta will automatically detect such differently-styled lines, and display them unchanged, i.e. with the raw colors it receives from Git.

To activate the Git feature, use

and see the Git documentation for the other possible values and associated color configuration.

In order to support this feature, Delta has to look at the raw colors it receives in a line from Git, and use them to judge whether it is a typical removed/added line, or a specially-colored moved line. This should just work. However, if it causes problems, the behavior can be disabled using

Use the navigate feature to activate navigation keybindings. In this mode, pressing n will jump forward to the next file in the diff, and N will jump backwards. If you are viewing multiple commits (e.g. via git log -p) then navigation will also visit commit boundaries.

The recommended way to use navigate is to activate it only when needed, for example by using the environment variable DELTA_NAVIGATE:

Please note that if the environment variable is set to anything at all (even "false" or "0" or "") then that is interpreted as true. The above command sets the environment variable in the child process only, so it has no permanent effect on your shell session. But if, for whatever reason, you do have it set in your shell environment then to deactivate it you must unset the environment variable (e.g. using unset DELTA_NAVIGATE). You cannot deactivate it by assigning a value to it.

An alternative is to mutate your git config file from the command line:

The reason that navigate should not be used all the time is that Delta uses less as its pager, and the navigate feature works by doing less --pattern <regex-matching-file-and-commit-lines>. When the git output does not contain file/commit diff lines, less --pattern behaves unhelpfully (see #234, #237).

Delta looks best if your terminal application supports 24 bit colors. See For example, on MacOS, iTerm2 supports 24-bit colors but does not.

If your terminal application does not support 24-bit color, delta will still work, by automatically choosing the closest color from those available. See the Colors section of the help output below.

If you're using tmux, it's worth checking that 24 bit color is working correctly. For example, run a color test script like this one, or one of the others listed here. If you do not see smooth color gradients, see the discussion at tmux#696. The short version is you need something like this in your ~/.tmux.conf:

and you may then need to quit tmux completely for it to take effect.

Delta works on Windows. However, the less.exe installed with git has some bugs: you will see incorrect colors and other problems. A patched version of less.exe and instructions for installing can be found here.

If mouse scrolling isn't working correctly, try setting your BAT_PAGER environment variable to (at least) less -R .

See issue #58 and bat README / "Using a different pager".

Delta can be used when displaying diffs in the Magit git client: see magit-delta. Here's a screenshot:

To list the supported languages and color themes, use delta --list-languages and delta --list-syntax-themes. To see a demo of the color themes, use delta --show-syntax-themes:

To add your own custom color theme, or language, please follow the instructions in the Customization section of the bat documentation:

Delta automatically recognizes custom themes and languages added to bat. You will need to install bat in order to run the bat cache --build command.

The languages and color themes that ship with delta are those that ship with bat. So, to propose a new language or color theme for inclusion in delta, it would need to be a helpful addition to bat, in which case please open a PR against bat.

You'll need to install the rust tools. Then:

and use the executable found at ./target/release/delta.