path: root/README.v0.2.0.md

[![Build Status](https://travis-ci.com/dandavison/delta.svg?branch=master)](https://travis-ci.com/dandavison/delta)
[![Gitter](https://badges.gitter.im/dandavison-delta/community.svg)](https://gitter.im/dandavison-delta/community?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge)

## A viewer for git and diff output

Code evolves, and studying diffs to understand how some code has changed is a fundamental mode of work. Delta aims to allow you to study diffs in exactly the way that you want. Some people stay fairly close to the default git/diff output, whereas others make extensive changes to layout and visual appearance. Delta wants your work to be both efficient and enjoyable, and it supports all of the above.

#### Delta's main features are:

- Language syntax highlighting with color themes
- Within-line highlights based on a Levenshtein edit inference algorithm
- Style (foreground color, background color, font attributes) can be configured independently for more than 20 different sections of the diff
- Stylable box/line decorations to draw attention to commit, file and hunk header sections.
- Line numbering (`-n`)
- Diff-highlight and diff-so-fancy emulation modes permitting incremental adoption of delta-specific features (`--diff-highlight`, `--diff-so-fancy`)
- Code can be copied directly from the diff (`-/+` markers are removed by default).
- `n` and `N` keybindings to move between files in large diffs, and between diffs in `log -p` views (`--navigate`)
- Named custom collections of key-value pairs ("features") to keep configuration files well-organized. (`--features`)
- An extensive test suite

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

<sub>

```
[core]
    pager = delta

[delta]
    features = decorations
    whitespace-error-style = 22 reverse

[delta "decorations"]
    commit-decoration-style = bold box ul
    file-style = bold 19 ul
    file-decoration-style = none
```

</sub>


Delta is evolving too. Planned features for the future include a side-by-side diff view and alternative within-line highlighting algorithms.

Contents
========

* [Features](#features)
* [Installation](#installation)
* [Configuration](#configuration)
* [Usage](#usage)
   * [Supported languages and themes](#supported-languages-and-themes)
   * [24 bit color (truecolor)](#24-bit-color-truecolor)
   * [Using Delta on Windows](#using-delta-on-windows)
   * [Mouse scrolling](#mouse-scrolling)
   * [Using Delta with Magit](#using-delta-with-magit)
   * [Using Delta with Mercurial](#using-delta-with-mercurial)
* [Comparisons with other tools](#comparisons-with-other-tools)
* [Build delta from source](#build-delta-from-source)
* [Credit](#credit)
* [Projects using delta](#projects-using-delta)
* [Full --help output](#full---help-output)

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

<br>

<table>
  <tr>
    <td>
      <img width=500px style="border: 1px solid black"
           src="https://user-images.githubusercontent.com/52205/81058545-a5725f80-8e9c-11ea-912e-d21954586a44.png"
           alt="image" />
    </td>
    <td>
      <img width=500px style="border: 1px solid black"
           src="https://user-images.githubusercontent.com/52205/81058911-6abcf700-8e9d-11ea-93be-e212824ec03d.png"
           alt="image" />
    </td>
  </tr>
  <tr>
    <td>
      "Dracula" theme
    </td>
    <td>
      "GitHub" theme
    </td>
  </tr>
</table>

<br>
<br>

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

<br>
<table><tr><td>
  <img width=650px src="https://user-images.githubusercontent.com/52205/81059276-254cf980-8e9e-11ea-95c3-8b757a4c11b5.png" alt="image" />
</td></tr></table>


<br>
<br>

**All the syntax-highlighting color themes that are available with [bat](https://github.com/sharkdp/bat/) are available with delta:**

<br>
<table>
  <tr>
    <td>
      <img width=500px style="border: 1px solid black"
           src="https://user-images.githubusercontent.com/52205/80850197-b8f5a000-8be8-11ea-8c9e-29c5b213c4b7.png"
           alt="image" />
    </td>
    <td>
      <img width=450px style="border: 1px solid black"
           src="https://user-images.githubusercontent.com/52205/80850237-e04c6d00-8be8-11ea-9027-0d2ea62f15c2.png"
           alt="image" />
    </td>
  </tr>
  <tr>
    <td>
      <code>delta --list-themes --dark</code>
    </td>
    <td>
      <code>delta --list-themes --light</code>
    </td>
  </tr>
</table>


<br>

## Features
|                                                | delta | git | [diff-so-fancy] /<br>[diff-highlight] | github/gitlab |
|------------------------------------------------|-------|-----|---------------------------------------|---------------|
| language syntax highlighting                   | ✅    | ❌  | ❌                                    | ✅           |
| within-line insertion/deletion detection       | ✅    | ❌  | ✅                                    | ✅           |
| multiple insertion/deletions detected per line | ✅    | ❌  | ❌                                    | ✅           |
| matching of unequal numbers of changed lines   | ✅    | ❌  | ❌                                    | ❌           |
| independently stylable elements                | ✅    | ✅  | ✅                                    | ❌           |
| line numbering                                 | ✅    | ❌  | ❌                                    | ✅           |

In addition, delta handles traditional unified diff output.

[diff-so-fancy]: https://github.com/so-fancy/diff-so-fancy
[diff-highlight]: https://github.com/git/git/tree/master/contrib/diff-highlight

## Installation

You can download an executable for your system: [Linux](https://github.com/dandavison/delta/releases/download/0.1.1/delta-0.1.1-x86_64-unknown-linux-musl.tar.gz) | [MacOS](https://github.com/dandavison/delta/releases/download/0.1.1/delta-0.1.1-x86_64-apple-darwin.tar.gz) | [Windows](https://github.com/dandavison/delta/releases/download/0.1.1/delta-0.1.1-x86_64-pc-windows-gnu.zip) | [All](https://github.com/dandavison/delta/releases)

Alternatively, delta is available in the following package managers:

<table>
  <tr>
    <td>Arch Linux (<a href="https://aur.archlinux.org/packages/git-delta">AUR</a>)</td>
    <td><code>yay -S git-delta</code>
        <br>or<br>
        <code>git clone https://aur.archlinux.org/git-delta.git</code><br>
        <code>cd git-delta</code><br>
        <code>makepkg -csri</code></td>
  </tr>
  <tr>
    <td>Debian</td>
    <td><br>.deb files are on the <a href="https://github.com/dandavison/delta/releases">releases</a> page and at <a href="https://github.com/barnumbirr/delta-debian/releases">barnumbirr/delta-debian</a><br>
    <code>dpkg -i file.deb</code></td>
  </tr>
  <tr>
    <td>Fedora</td>
    <td><code>dnf install git-delta</code></td>
  </tr>
  <tr>
    <td>FreeBSD</td>
    <td><code>pkg install git-delta</code></td>
  </tr>
  <tr>
    <td>Homebrew</td>
    <td><code>brew install git-delta</code></td>
  </tr>
  <tr>
    <td>MacPorts</td>
    <td><code>port install git-delta</code></td>
  </tr>
  <tr>
    <td>Nix</td>
    <td><code>nix-env -iA nixpkgs.gitAndTools.delta</code>
  </tr>
  <tr>
    <td>Windows (<a href="https://chocolatey.org/packages/delta">Chocolatey</a>)</td>
    <td><code>choco install delta</code></td>
  </tr>
</table>

## Configuration

Set delta to be git's pager in your `.gitconfig`. Delta accepts many command line options to alter colors and other details of the output. An example is
```
[core]
    pager = delta

[delta]
    plus-color = "#012800"
    minus-color = "#340001"
    theme = 'Monokai Extended'

[interactive]
    diffFilter = delta --color-only
```

Note that delta argument values in ~/.gitconfig should be in double quotes, like `--minus-color="#340001"`. For a theme name containing a space, use single quotes, like `--theme='Monokai Extended'`.

All git commands that display diff output should now display syntax-highlighted output. For example:
  - `git diff`
  - `git show`
  - `git log -p`
  - `git stash show -p`
  - `git reflog -p`
  - `git add -p`

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:
```
diff -u a.txt b.txt | delta
delta a.txt b.txt
```

## Usage

### Supported languages and themes
To list the supported languages and color themes, use `delta --list-languages` and `delta --list-theme-names`. To see a demo of the color themes, use `delta --list-themes`:

To add your own custom color theme, or language, please follow the instructions in the Customization section of the [bat documentation](https://github.com/sharkdp/bat/#customization):
- [Adding a custom language](https://github.com/sharkdp/bat/#adding-new-syntaxes--language-definitions)
- [Adding a custom theme](https://github.com/sharkdp/bat/#adding-new-themes)

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.

### 24 bit color (truecolor)

Delta looks best if your terminal application supports 24 bit colors. See https://gist.github.com/XVilka/8346728. For example, on MacOS, iTerm2 supports 24-bit colors but Terminal.app 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](https://gist.githubusercontent.com/lifepillar/09a44b8cf0f9397465614e622979107f/raw/24-bit-color.sh),  or one of the others listed [here](https://gist.github.com/XVilka/8346728). If  you do not see smooth color gradients, see the discussion at  [tmux#696](https://github.com/tmux/tmux/issues/696). The short  version is you need something like this in your `~/.tmux.conf`:
```
set -ga terminal-overrides ",xterm-256color:Tc"
```
and you may then  need to quit tmux completely for it to take effect.


### Using Delta on Windows

Delta works with Windows. However, the `less.exe` installed with git doesn't work well with `delta`. A patched version of `less.exe` and instructions for installing can be found [here](https://github.com/lzybkr/less/releases/tag/fix_windows_vt).


### Mouse scrolling

If mouse scrolling isn't working correctly, try setting your `BAT_PAGER` environment variable to (at least) `less -R` .
See [issue #58](https://github.com/dandavison/delta/issues/58) and [bat README / "Using a different pager"](https://github.com/sharkdp/bat#using-a-different-pager).


### Using Delta with Magit

Delta can be used when displaying diffs in the Magit git client: see [magit-delta](https://github.com/dandavison/magit-delta). Here's a screenshot:

<table><tr><td><img width=500px src="https://user-images.githubusercontent.com/52205/79934267-2acb2e00-8420-11ea-8bc4-546508fd3581.png" alt="image" /></td></tr></table>


### Using Delta with Mercurial

Add delta to the `[pager]` section of `.hgrc`, the same way as `~/.gitconfig`.



## Comparisons with other tools

(`delta --light`)



<table>
  <tr>
    <td>
      delta vs. git
    </td>
    <td>
      <img width=500px style="border: 1px solid black"
           src="https://user-images.githubusercontent.com/52205/65248525-32250480-daea-11e9-9965-1a05c6a4bdf4.png"
           alt="image" />
    </td>
    <td>
      <img width=500px style="border: 1px solid black"
           src="https://user-images.githubusercontent.com/52205/65248441-14f03600-daea-11e9-88a1-d96bbb6947f8.png"
           alt="image" />
    </td>
  </tr>
  <tr>
    <td>
      delta vs. diff-so-fancy /<br>diff-highlight
    </td>
    <td>
      <img width=500px style="border: 1px solid black"
           src="https://user-images.githubusercontent.com/52205/65248525-32250480-daea-11e9-9965-1a05c6a4bdf4.png"
           alt="image" />
    </td>
    <td>
      <img width=500px style="border: 1px solid black"
           src="https://user-images.githubusercontent.com/52205/65248407-07d34700-daea-11e9-9a8f-6d81f4021abf.png"
           alt="image" />
    </td>
  </tr>
  <tr>
    <td>
      delta vs. github
    </td>
    <td>
      <img width=500px style="border: 1px solid black"
           src="https://user-images.githubusercontent.com/52205/65248525-32250480-daea-11e9-9965-1a05c6a4bdf4.png"
           alt="image" />
    </td>
    <td>
      <img width=500px style="border: 1px solid black"
           src="https://user-images.githubusercontent.com/52205/65248749-9a73e600-daea-11e9-9c0d-29c8f1dea08e.png"
           alt="image" />
    </td>
  </tr>
</table>


## Build delta from source

You'll need to [install the rust tools](https://www.rust-lang.org/learn/get-started). Then:

```
cargo build --release
```

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


## Credit
- [ogham/rust-ansi-term](https://github.com/ogham/rust-ansi-term)
- [sharkdp/bat](https://github.com/sharkdp/bat)
- [so-fancy/diff-so-fancy](https://github.com/so-fancy/diff-so-fancy)
- [trishume/syntect](https://github.com/trishume/syntect)


## Projects using delta
- [wfxr/forgit](https://github.com/wfxr/forgit)
- [bigH/git-fuzzy](https://github.com/bigH/git-fuzzy)
- [dandavison/magit-delta](https://github.com/dandavison/magit-delta)
- [jesseduffield/lazygit](https://github.com/jesseduffield/lazygit/)
- [ms-jpq/sad](https://github.com/ms-jpq/sad)


## Full --help output

```
delta 0.2.0
A viewer for git and diff output

USAGE:
    delta [FLAGS] [OPTIONS] [ARGS]

FLAGS:
        --light                      Use default colors appropriate for a light terminal background. For more control,
                                     see the style options
        --dark                       Use default colors appropriate for a dark terminal background. For more control,
                                     see the style options
        --diff-highlight             Emulate diff-highlight (https://github.com/git/git/tree/master/contrib/diff-
                                     highlight)
        --diff-so-fancy              Emulate diff-so-fancy (https://github.com/so-fancy/diff-so-fancy)
        --navigate                   Activate diff navigation: use n to jump forwards and N to jump backwards. To change
                                     the file labels used see --file-modified-label, --file-removed-label, --file-added-
                                     label, --file-renamed-label
    -n, --line-numbers               Display line numbers next to the diff. See LINE NUMBERS