---
obj: application
website: https://dandavison.github.io/delta/
repo: https://github.com/dandavison/delta
---

# Delta
A syntax-highlighting pager for git, diff, grep, and blame output

## Get started
Install delta and add this to your `~/.gitconfig`:

```ini
[core]
    pager = delta

[interactive]
    diffFilter = delta --color-only

[delta]
    navigate = true    # use n and N to move between diff sections

    # delta detects terminal colors automatically; set one of these to disable auto-detection
    # dark = true
    # light = true

[merge]
    conflictstyle = zdiff3
```

### Configuration
Delta uses git config (`~/.gitconfig`) for its configuration.

You do not even need to use git -- delta accepts git diff and unified diff formats and hence works with e.g. mercurial and jujutsu -- but you do need to use the git config format.

Use `delta --help` to see all the available options.

To change your delta options in a one-off git command, use `git -c`. For example

```shell
git -c delta.line-numbers=false show
```

## Usage
The main way to use delta is to configure it as the pager for git.

Delta can also be used as a shorthand for diffing two files, even if they are not in a git repo: the following two commands do the same thing:

```shell
delta /somewhere/a.txt /somewhere/else/b.txt

git diff /somewhere/a.txt /somewhere/else/b.txt
```

You can also use process substitution shell syntax with delta, e.g.

```bash
delta <(sort file1) <(sort file2)
```

In addition to git output, delta handles standard unified diff format, e.g. `diff -u a.txt b.txt | delta`.

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

### Choosing colors (styles)
Delta detects your terminal background color automatically and chooses appropriate default colors. To override automatic detection use dark or light, e.g.

```ini
[delta]
    dark = true
```

This is necessary when running delta in some contexts such as lazygit or zellij.

### Line numbers

```ini
[delta]
    line-numbers = true
```

The numbers are displayed in two columns and there are several configuration options: see the `LINE NUMBERS` section in `delta --help` for details.

### Hyperlinks
Delta uses terminal hyperlinks to turn line numbers, file paths, commit hashes, etc into clickable links, as long as your terminal emulator supports it. Enable the feature with

```ini
[delta]
    hyperlinks = true
```

Commit hashes link to GitHub/GitLab/Bitbucket (use `hyperlinks-commit-link-format` for full control).

The links on line numbers (in grep output, as well as diffs) are particularly interesting: with a little bit of effort, they can be made to open your editor or IDE at the correct line. Use `hyperlinks-file-link-format` to construct the correct URL for your system. For VSCode and JetBrains IDEs this is easy, since they support their own special URL protocols. Here are examples:

```ini
[delta]
    hyperlinks = true
    hyperlinks-file-link-format = "vscode://file/{path}:{line}"
    # hyperlinks-file-link-format = "idea://open?file={path}&line={line}"
    # hyperlinks-file-link-format = "pycharm://open?file={path}&line={line}"
```

Zed also supports its own URL protocol, and probably others.

If your editor does not have its own URL protocol, then there are still many possibilities, although they may be more work.

The easiest is probably to write a toy HTTP server (e.g. in Python) that opens the links in the way that you need. Then your delta config would look something like

```ini
[delta]
hyperlinks = true
hyperlinks-file-link-format = "http://localhost:8000/open-in-editor?path={path}&line={line}"
# Now write an HTTP server that handles those requests by opening your editor at the file and line
```

### Side-by-side view

```ini
[delta]
    side-by-side = true
```

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

### Grep
Delta applies syntax-highlighting and other enhancements to standard grep output such as from ripgrep (aka rg), git grep, grep, etc. If you don't need special features of git grep, then for best results pipe `rg --json` output to delta: this avoids parsing ambiguities that are inevitable with the output of git grep and grep. To customize the colors and syntax highlighting, see the `grep-*` options in `delta --help`.

Note that git grep can display the "function context" for matches and that delta handles this output specially: see the `-p` and `-W` options of git grep.

```shell
rg --json -C 2 handle | delta
```

With hyperlinks enabled, the line numbers in the grep output will be clickable links. See hyperlinks.

### Navigation keybindings for large diffs
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.

### Merge conflicts
Consider setting `merge.conflictStyle` to `zdiff3`:

```ini
[merge]
    conflictStyle = zdiff3
```

With that setting, when a merge conflict is encountered, Git will display merge conflicts with the contents of the merge base as well. delta will then display this as two diffs, from the ancestor to each side of the conflict:

### Git blame
Set delta as the pager for blame in the `[pager]` section of your gitconfig. If hyperlinks is enabled in the `[delta]` section then each blame commit will link to the commit on GitHub/GitLab/Bitbucket/etc.
