A git diff pager based on delta but with a file tree, à la GitHub.

Mathew's personal fork of dlvhdr/diffnav, focused on speeding up local code review in the AI age. See IDEAS.md for the roadmap.

Installation

This fork is not published to Homebrew. Install from source:

go install github.com/matart/diffnav@latest

Or clone and build:

git clone https://github.com/matart/diffnav.git
cd diffnav
go install .

Note

To get the icons to render properly you should download and install a Nerd font from https://www.nerdfonts.com/. Then, select that font as your font for the terminal.

You can install these with brew as well: brew install --cask font-<FONT NAME>-nerd-font

Usage

Pipe into diffnav

• git diff | diffnav
• gh pr diff <PR URL> | diffnav

Set up as Global Git Diff Pager

git config --global pager.diff diffnav

Flags

Flag	Description
--side-by-side, -s	Force side-by-side diff view
--unified, -u	Force unified diff view
--watch, -w	Watch mode: periodically re-run a command and refresh
--watch-cmd	Command to run in watch mode (implies --watch, default: git diff)
--watch-interval	Interval between watch refreshes (default: 2s)

Example:

git diff | diffnav --unified
git diff | diffnav -u

Watch Mode

Watch mode lets diffnav periodically re-run a diff command and refresh the display automatically. This is useful for monitoring changes as you work.

# watch unstaged changes (default: git diff, every 2s)
diffnav --watch

# watch staged changes with a custom interval
diffnav --watch-cmd "git diff --cached" --watch-interval 5s

# watch changes against a specific branch
diffnav --watch-cmd "git diff main..."

Configuration

The config file is searched in this order:

1. $DIFFNAV_CONFIG_DIR/config.yml (if env var is set)
2. $XDG_CONFIG_HOME/diffnav/config.yml (if set, macOS only)
3. ~/.config/diffnav/config.yml (macOS and Linux)
4. OS-specific config directory (e.g., ~/Library/Application Support/diffnav/config.yml on macOS)

Example config file:

ui:
  # Hide the header to get more screen space for diffs
  hideHeader: true

  # Hide the footer (keybindings help)
  hideFooter: true

  # Start with the file tree hidden (toggle with 'e')
  showFileTree: false

  # Customize the file tree width (default: 26)
  fileTreeWidth: 30

  # Customize the search panel width (default: 50)
  searchTreeWidth: 60

  # Icon style: "status" (default), "simple", "filetype", "full", "unicode", or "ascii"
  icons: nerd-fonts-status

  # Color filenames by git status (default: true)
  colorFileNames: false

  # Show the amount of lines added / removed next to the file
  showDiffStats: false

  # Use side-by-side diff view (default: true, set false for unified)
  sideBySide: true

  # How many levels of folders to open on start (-1 = all, 0 = none, 1 = first level, etc.)
  startFoldersOpenDepth: 1

Option	Type	Default	Description
ui.hideHeader	bool	false	Hide the "DIFFNAV" header
ui.hideFooter	bool	false	Hide the footer with keybindings help
ui.showFileTree	bool	true	Show file tree on startup
ui.fileTreeWidth	int	26	Width of the file tree sidebar
ui.searchTreeWidth	int	50	Width of the search panel
ui.icons	string	nerd-fonts-status	Icon style (see below for details)
ui.colorFileNames	bool	true	Color filenames by git status
ui.showDiffStats	bool	true	Show the amount of lines added / removed next to the file
ui.sideBySide	bool	true	Use side-by-side diff view (false for unified)
ui.startFoldersOpenDepth	int	-1	Folder open depth on start (-1 = all, 0 = none)

Icon Styles

Style	Description
nerd-fonts-status	Boxed git status icons colored by change type
nerd-fonts-simple	Generic file icon colored by change type
nerd-fonts-filetype	File-type specific icons (language icons) colored by change type
nerd-fonts-full	Both status icon and file-type icon, all colored
unicode	Unicode symbols (+/⛌/●)
ascii	Plain ASCII characters (+/x/*)

Storage

diffnav persists reviewed-hunk markers (toggled with r) to a JSON file. By default it's ~/.local/share/diffnav/reviewed.json (or $XDG_DATA_HOME/diffnav/ if set). Override via env var or config:

storage:
  path: ~/Library/Application Support/diffnav

Env var override: DIFFNAV_STORAGE_DIR (priority: env > yaml > default).

Delta

You can also configure the diff rendering through delta. Check out their docs.

This fork's delta config lives at cfg/delta.conf.

Keys

Key	Description
j	Next node
k	Previous node
n	Next file
p / N	Previous file
Ctrl-d	Scroll the diff down
Ctrl-u	Scroll the diff up
e	Toggle the file tree
t	Search/go-to file
y	Copy file path
i	Cycle icon style
o	Open file in $EDITOR
r	Toggle current hunk as reviewed
] / [	Next / previous hunk
s	Toggle side-by-side/unified view
Tab	Switch focus between the panes
q	Quit

Credits

This is a fork of dlvhdr/diffnav. All credit for the original tool goes to @dlvhdr and the upstream contributors. If you want to support the upstream project, see the sponsors page.

Under the Hood

diffnav uses:

• Bubble Tea for the TUI
• delta for viewing the diffed file