delta Git Diff Viewer

delta cheatsheet — configure syntax-highlighted git diffs, side-by-side views, line numbers. Set delta as git pager in .gitconfig. The git diff upgrade.

7 min read

What it is

delta is a powerful tool that enhances the output of git diff, git log, and git show with syntax highlighting, side-by-side views, and much more, making code review and understanding changes significantly easier.

Installation

Linux

# Using cargo (Rust's package manager)
cargo install git-delta

# Using package managers (check for availability in your distro's repositories)
# Debian/Ubuntu
sudo apt update
sudo apt install git-delta

# Fedora
sudo dnf install git-delta

# Arch Linux
sudo pacman -S git-delta

macOS

# Using Homebrew
brew install git-delta

Windows

# Using Scoop
scoop install git-delta

# Using Cargo
cargo install git-delta

Core Concepts

Syntax Highlighting: delta analyzes the content of diffs and applies syntax highlighting based on the file type.
Side-by-Side View: By default, delta presents diffs in a side-by-side format, allowing for easier comparison of changes.
Line Numbers: Adds clear line numbering to both the original and new versions of the file.
Whitespace Handling: Offers various options for visualizing and ignoring whitespace changes.
File Headers: Enhances file headers with diff statistics and file names.
Navigation: Provides basic navigation within the diff output.

Commands / Usage

To use delta with git, you typically configure git to use delta as its diff pager. This is done by adding the following to your ~/.gitconfig file:

[core]
    pager = delta
[delta]
    # Optional: Enable syntax highlighting
    syntax-theme = Monokai
    # Optional: Enable side-by-side view
    side-bare = true

Once configured, delta will be used automatically by git diff, git log, and git show.

Basic Usage (after configuration)

# View changes in the working directory
git diff

# View staged changes
git diff --staged

# View changes for a specific file
git diff HEAD -- README.md

# View commit history
git log

# View commit history with diffs for each commit
git log -p

# View changes introduced by a specific commit
git show abc1234

# View changes between two branches
git diff main..feature-branch

`git diff` with `delta` Flags (can be passed via `git -c delta.<option>=<value>`)

These flags can be added directly to git diff commands using git -c delta.<option>=<value>. For example: git -c delta.side-bare=false diff.

Layout & Appearance

--color-only: Print diff in color, but not syntax highlight.
```
git diff --color-only
```
Prints the diff with ANSI color codes, but without applying file-specific syntax highlighting.
--side-bare: Enable side-by-side view.
```
git diff --side-bare
```
Displays the diffs side-by-side, making it easier to compare lines.
--side-by-side: Alias for --side-bare.
```
git diff --side-by-side
```
Same as --side-bare.
--no-side-bare: Disable side-by-side view.
```
git diff --no-side-bare
```
Displays the diff in the traditional unified format.
--line-numbers: Show line numbers.
```
git diff --line-numbers
```
Adds line numbers to the diff output.
--no-line-numbers: Hide line numbers.
```
git diff --no-line-numbers
```
Removes line numbers from the diff output.
--syntax-theme <theme>: Set the syntax highlighting theme.
```
git diff --syntax-theme="OneHalfDark"
```
Applies the specified syntax theme (e.g., OneHalfDark, Monokai, Solarized) to the diff output.
--theme <theme>: Alias for --syntax-theme.
```
git diff --theme="Dracula"
```
Same as --syntax-theme.
--plus-style <style>: Customize the style for added lines.
```
git diff --plus-style="bg-green"
```
Applies a specific style (e.g., bold, bg-blue, red) to lines that were added.
--minus-style <style>: Customize the style for removed lines.
```
git diff --minus-style="bg-red"
```
Applies a specific style to lines that were removed.
--hunk-header-style <style>: Customize the style for hunk headers.
```
git diff --hunk-header-style="bold yellow"
```
Applies a style to the @@ ... @@ lines that indicate the location of changes.
--file-header-style <style>: Customize the style for file headers.
```
git diff --file-header-style="red bold"
```
Applies a style to the lines indicating the files being diffed (e.g., --- a/file.txt, +++ b/file.txt).

Whitespace Handling

--whitespace-error-style <style>: Style for whitespace errors.
```
git diff --whitespace-error-style="bg-red bold"
```
Highlights lines containing whitespace errors (e.g., trailing whitespace) with the specified style.
--show-whitespace-errors: Show only lines with whitespace errors.
```
git diff --show-whitespace-errors
```
Filters the diff to only display lines that contain whitespace errors.
--hide-whitespace-errors: Hide lines with whitespace errors.
```
git diff --hide-whitespace-errors
```
Suppresses lines that contain whitespace errors from the diff output.
--wrap-words: Wrap long lines that exceed terminal width.
```
git diff --wrap-words
```
When lines are too long, they will be wrapped to fit the terminal width, improving readability.
--unwrap-words: Disable word wrapping.
```
git diff --unwrap-words
```
Disables the word wrapping behavior.

Other Options

--diff-highlight: Enable diff highlighting (part of delta’s core functionality).
```
git diff --diff-highlight
```
This is generally enabled by default when delta is configured as the pager. It applies specific highlighting to added and removed lines.
--commit-header-style <style>: Customize the style for commit headers in git log.
```
git log -p --commit-header-style="blue bold"
```
Applies a style to the commit hash and author information when viewing logs with diffs.
--grep <pattern>: Search commit messages for a pattern (when used with git log).
```
git log --grep="fix"
```
Filters the log to show only commits whose messages contain the word "fix". delta will then display the diffs for these filtered commits.

Common Patterns

Viewing Changes with Specific Syntax Highlighting

git diff -c delta.syntax-theme="SolarizedLight"

View your unstaged changes using the "SolarizedLight" syntax theme.

Side-by-Side Diff with Added Line Highlighting

git diff -c delta.side-bare=true -c delta.plus-style="bg-green bold" HEAD -- src/main.rs

Show changes in src/main.rs side-by-side, with added lines highlighted in bold green.

Verbose Log with Diff and Specific Commit Header Style

git log -p -c delta.commit-header-style="cyan"

Display the commit history with full diffs for each commit, and style commit headers in cyan.

Ignoring Whitespace Errors in Diffs

git diff -c delta.hide-whitespace-errors=true

View unstaged changes, but hide any lines that contain whitespace errors.

Customizing Added/Removed Line Styles Globally

Add these to your ~/.gitconfig under [delta]:

[delta]
    plus-style = "bg-green"
    minus-style = "bg-red"

This will automatically apply green background to added lines and red background to removed lines for all git diff outputs.

Diffing Specific Files Across Commits

git diff abc1234^ abc1234 -- README.md

Show the changes to README.md introduced by commit abc1234 by diffing it against its parent.

Diffing Between Two Branches Side-by-Side

git diff --side-bare main feature-branch

Compare the main and feature-branch branches side-by-side.

Gotchas

Configuration Overrides: Flags passed directly to git diff (e.g., git diff --no-side-bare) will override settings in your ~/.gitconfig.
Terminal Support: delta relies on ANSI escape codes for color and styling. Ensure your terminal emulator supports them. Some older or basic terminals might not render colors correctly.
Performance with Large Diffs: For extremely large diffs or very large files, delta might introduce a slight performance overhead compared to the default git diff pager due to its enhanced processing.
Syntax Highlighting Accuracy: While delta is good, its syntax highlighting is based on heuristics and file extensions. It might occasionally misinterpret code or apply the wrong language highlighting, especially for files with unusual extensions or mixed content.
Piping to Other Commands: When piping git diff output to other commands, delta might interfere if it’s configured as the default pager. You might need to explicitly disable delta or use git diff --no-pager in such cases.
```
git diff --no-pager | grep "TODO"
```
git log -p vs. git diff: While delta enhances both, git log -p shows diffs for each commit sequentially, whereas git diff shows the overall difference between two states (working tree, index, commits, etc.). The configuration applies to both.