git difftool

Hands diffs to meld/vimdiff/etc.

🎯 What & why

git difftool hands diffs to an external viewer (meld, vimdiff, kdiff3, Beyond Compare, VS Code) instead of dumping unified diff to your terminal. Indispensable when the diff is bigger than your eyeballs.

🧠 Mental model

Same engine as git diff, different frontend. Whatever git diff would show, difftool ships to a configured GUI or TUI tool one file at a time - or the whole tree at once with -d.

🛠️ Synopsis

git difftool [--tool=<tool>] [-d|--dir-diff] [-y|--no-prompt]
                  [-x <command>] [--gui] [--trust-exit-code]
                  [<diff-options>] [<commit> [<commit>]] [--] [<path>...]

🎚️ Switches & options

Flag	What it does
`--tool=<tool>`	Pick the tool: meld, vimdiff, kdiff3, bc, vscode, etc.
`-d, --dir-diff`	Diff entire working trees side-by-side instead of file-by-file
`-y, --no-prompt`	Skip the 'Launch tool?' prompt for every file
`-x <command>`	Run an arbitrary command on each pair instead of a configured tool
`--gui`	Use diff.guitool instead of diff.tool
`--trust-exit-code`	Honor the tool's exit code (so scripts can detect cancel)
`difftool.<tool>.cmd (config)`	Define a custom command template using $LOCAL and $REMOTE

💡 Use cases

Reviewing a large refactor across many files at once
Visually comparing two branches before merging
Eyeballing whitespace and structural changes in code
Comparing arbitrary commits without leaving your editor

🧪 Examples

Whole-tree review with meld

git difftool -d -t meld main..feature

Skip per-file prompts

git difftool -y HEAD~3 HEAD

VS Code as gui tool

git difftool --gui -d

Ad-hoc tool via -x

git difftool -x "diff -u" HEAD~1

🎓 Recommendations

Set diff.tool once in ~/.gitconfig so you do not type --tool every time.
Use -d for code review - it beats stepping through 40 files individually.
Combine with --no-prompt unless you genuinely want to skip files interactively.

🪤 Common pitfalls

Without --trust-exit-code, cancelling the tool is silently ignored.
-d copies files to a temp directory - editing them there does not stage anything.
Some tools (vimdiff) take over the terminal - run from a separate pane if you scripted it.

🔗 Related modules

📝 Quiz

Hit each option, then Check answers. Score is recorded; Next is always open.