5.4 KiB
| obj | website | repo |
|---|---|---|
| application | https://dandavison.github.io/delta/ | 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:
[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
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:
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.
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.
[delta]
dark = true
This is necessary when running delta in some contexts such as lazygit or zellij.
Line numbers
[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
[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:
[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
[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
[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.
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:
[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.