DOCSEARCHbyAlgolia
Submit Docs

diffnav

repository·main·Indexed 23 days ago

https://github.com/dlvhdr/diffnav

A git diff pager built on the delta engine that provides a GitHub-style file tree alongside diff views. It supports manual piping, global Git configuration, and a watch mode for real-time monitoring of changes via custom commands and intervals.

Tokens
4.1K
Snippets
10
Records
12
Agent score
31%

What's inside diffnav

  1. Use Watch Mode in diffnav

    main

    Watch mode periodically re-runs a specified command and refreshes the display, which is useful for monitoring changes in real-time.

    • Watch unstaged changes: By default, this runs git diff every 2 seconds.
    • Watch staged changes: Use --watch-cmd to specify the command and --watch-interval to set the frequency.
    • Watch against a branch: Use --watch-cmd to specify a diff against a specific branch.
    # 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..."

  2. Install diffnav

    main

    You can install diffnav using Homebrew or by compiling from source with Go.

    Note on Icons: To render icons correctly, you must install and use a Nerd Font in your terminal. You can install them via Homebrew using brew install --cask font-<FONT_NAME>-nerd-font.

    # Using Homebrew
brew install diffnav

# Or from the tap directly
brew install dlvhdr/formulae/diffnav

# Using Go
git clone https://github.com/dlvhdr/diffnav.git
cd diffnav
go install .

  3. Use diffnav as a pager or via piping

    main

    You can use diffnav manually by piping diff output into it, or set it as your default global Git diff pager.

    Manual Piping:

    git diff | diffnav

    Global Git Configuration: To make diffnav your default pager for all git diff commands, run:

    git config --global pager.diff diffnav

  4. Configure diffnav via config.yml

    main

    You can customize the diffnav user interface using a config.yml file. The application searches for this file in the following order:

    1. $DIFFNAV_CONFIG_DIR/config.yml (if the environment variable is set)
    2. $XDG_CONFIG_HOME/diffnav/config.yml (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)

    Configuration is divided into ui settings for the interface and can also be extended via delta for diff rendering.

    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

  5. Use diffnav as a git diff pager

    main

    You can use diffnav to view git diffs with a file tree interface similar to GitHub. There are two primary ways to integrate it:

    1. Pipe input manually: Pipe the output of any git command into diffnav.
    2. Set as global git pager: Configure git to use diffnav automatically whenever you run git diff.

    Note: diffnav expects a unified diff format as input. If the input is not a valid unified diff, it will print the input as-is and exit.

    # pipe into diffnav
git diff | diffnav

# use with the GitHub CLI
gh pr diff https://github.com/dlvhdr/gh-dash/pull/447 | diffnav

# set up as the global git diff pager
git config --global pager.diff diffnav

  6. Configure diffnav watch mode

    main

    Watch mode allows diffnav to periodically re-run a specified command and refresh the diff view automatically. This is useful for monitoring ongoing changes.

    • Use --watch to enable watch mode (defaults to running git diff).
    • Use --watch-cmd to specify a custom command to run.
    • Use --watch-interval to set the refresh rate (e.g., 5s, 1m).

    Warning: In watch mode, stdin input is ignored.

    # watch mode: auto-refresh a diff command
diffnav --watch

# watch with a custom command and interval
diffnav --watch --watch-cmd "git diff HEAD" --watch-interval 5s

  7. Reference: Icon styles for diffnav

    main

    The ui.icons configuration option supports several styles for displaying file and status information.

    | 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/\*)                                          |

  8. Reference: UI configuration options

    main

    The following options are available under the ui key in your config.yml file.

    | 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)           |

  9. Reference: diffnav CLI flags

    main

    The following flags are available for controlling the diffnav display and behavior.

    | 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`)                      |

  10. Reference: diffnav keybindings

    main

    Use these keyboard shortcuts to navigate the TUI and manage diff views.

    | Key                         | Description                                                     |
| :------------------------- | :-------------------------------------------------------------- |
| <kbd>j</kbd>                | Next node                                                       |
| <kbd>k</kbd>                | Previous node                                                   |
| <kbd>n</kbd>                | Next file                                                       |
| <kbd>p</kbd> / <kbd>N</kbd> | Previous file                                                   |
| <kbd>Ctrl-d</kbd>           | Scroll the diff half page down                                  |
| <kbd>Ctrl-u</kbd>           | Scroll the diff half page up                                    |
| <kbd>Ctrl-e</kbd>           | Scroll the diff one line down                                   |
| <kbd>Ctrl-y</kbd>           | Scroll the diff one line up                                     |
| <kbd>e</kbd>                | Toggle the file tree                                            |
| <kbd>t</kbd>                | Search/go-to file                                               |
| <kbd>y</kbd>                | Copy file path                                                  |
| <kbd>i</kbd>                | Cycle icon style                                                |
| <kbd>o</kbd>                | Open file in $EDITOR                                            |
| <kbd>s</kbd>                | Toggle side-by-side/unified view                                |
| <kbd>Tab</kbd>             | Switch focus between the panes                                 |
| <kbd>q</kbd>                | Quit                                                            |

  11. diffnav CLI flags reference

    main

    The following flags are available for the diffnav command:

    FlagShorthandDescription
    --side-by-side-sForce side-by-side diff view
    --unified-uForce unified diff view
    --watch-wWatch mode: periodically re-run a diff command and refresh
    --watch-cmd(none)Command to run in watch mode (default: git diff)
    --watch-interval(none)Interval between watch refreshes (default: 2s)

  12. Enable debug logging with DEBUG environment variable

    main
    To debug diffnav, set the DEBUG environment variable to true. This will cause the application to write detailed logs to a file named debug.log in the current working directory instead of stderr.