Use git difftool Safely for Working-Tree and Commit Reviews

You will finish with a repeatable way to inspect a Git change in a visual or terminal diff tool, including a safe command that works without a graphical session. The examples match Git 2.43.0 and git-man package version 1:2.43.0-1ubuntu7.3 installed on this machine.

Allow about ten minutes. You need Git, a repository with at least one commit, and a diff program. This guide starts with read-only comparisons. It does not require sudo, change repository configuration, or alter a commit. A configured editor may let you change files, so review the command before accepting any write operation.

1. Check the installed tool and available viewers

Confirm the Git version, then ask Git which difftool integrations it can find:

$ git --version
git version 2.43.0
$ git difftool --tool-help
'git difftool --tool=<tool>' may be set to one of the following:
        vimdiff           Use Vim
        ...

The exact list depends on programs installed on your host. Entries marked as unavailable cannot be launched successfully. A graphical tool also needs a working graphical session. If you are connected over SSH without display forwarding, choose a terminal tool or use the external command in the next step.

2. Run a terminal-safe comparison

--extcmd lets you provide a viewer command directly. Git invokes it with the temporary pre-image and post-image paths as its two arguments. This example uses the standard diff program and will not edit either side:

$ git difftool --no-prompt --extcmd='diff -u' -- path/to/file.txt
--- /tmp/git-blob-XXXXXX/path/to/file.txt
+++ path/to/file.txt
@@ -1 +1 @@
-old line
+new line

Replace path/to/file.txt with a tracked path in your repository. The -- separates revisions and options from paths, which prevents a filename beginning with a hyphen being interpreted as another option.

Git normally compares the working tree with the index when no revisions are supplied. If the file is unchanged relative to the index, there is nothing to open. To compare the working tree with the latest commit instead, name HEAD:

$ git difftool --no-prompt --extcmd='diff -u' HEAD -- path/to/file.txt

3. Choose a configured tool and control prompts

For a normal tool integration, pass its name with --tool:

$ git difftool --tool=vimdiff HEAD -- path/to/file.txt

Without --tool, Git uses diff.tool if it is configured, then selects a suitable default. Git prompts before each tool invocation by default. Use --no-prompt for a deliberate non-interactive run, or --prompt when a configuration setting has disabled prompts. The directory mode --dir-diff never prompts before launching the tool.

Do not add --no-prompt to a command you have not already tested. It removes the pause that lets you skip the next file, and a tool may open many files for a broad comparison:

$ git difftool --prompt HEAD~1 HEAD -- src/

This compares two commits only for paths below src/. The revisions and the path are positional Git arguments, so keep -- before the pathspec when there is any ambiguity.

4. Review several files without losing your place

Use directory mode when a directory-oriented viewer is more useful than one window per file:

$ git difftool --dir-diff HEAD~1 HEAD -- src/

Git copies modified files to a temporary location and starts a directory diff. In this mode it may create symlinks to working-tree files when the right-hand content is identical to the working tree. Use --no-symlinks if the viewer handles ordinary files more reliably:

$ git difftool --dir-diff --no-symlinks HEAD~1 HEAD -- src/

Use --skip-to=path/to/file.txt to begin at a file and omit earlier paths. Use --rotate-to=path/to/file.txt to begin there but move earlier paths to the end. These options affect review order, not the commits or the working tree.

5. Configure a tool only when you need it

A repository or global Git configuration can provide a default:

$ git config --global diff.tool vimdiff
$ git config --global --get diff.tool
vimdiff

This changes future invocations for your user account. If you only want a one-off choice, keep using --tool and avoid configuration. To undo the example setting, remove the value:

$ git config --global --unset diff.tool

For a tool outside Git's built-in set, configure difftool.<tool>.cmd. Git evaluates that command in a shell and supplies LOCAL, REMOTE, MERGED, and BASE. Treat these as filenames, quote them, and do not paste untrusted text into a shell command. A full executable path can instead be set with difftool.<tool>.path.

6. Interpret failures and exit codes

By default, Git ignores a non-zero status returned by an individual diff tool. That is convenient for interactive viewers, but it can hide a missing dependency or a viewer error in automation. Add --trust-exit-code when the caller must receive the tool's status:

$ git difftool --trust-exit-code --extcmd='diff -u' HEAD -- path/to/file.txt
$ printf '%s\n' "$?"
0

Do not interpret a successful difftool status as proof that the files are identical. It only means the invoked command returned success. Conversely, a non-zero result can mean that the viewer found differences, failed to start, or reported its own error. Check the external command's documented exit convention before using this option in a script.

If a tool opens no window, first run git difftool --tool-help. Then check that the selected program is available and that your graphical session is usable. The fallback for --gui is also configuration-dependent: Git consults diff.guitool, then related merge and diff tool settings. Do not use --gui as a repair for a missing display.