Introduction

If you do not enjoy reading unified diff output in the terminal, Git can launch an external diff tool instead. This is built into Git through git difftool, and it works with GUI tools such as Meld, Beyond Compare, KDiff3, or Visual Studio Code.

The usual setup is simple: tell Git which tool you want, optionally define the exact launch command, and then run git difftool whenever you want a visual comparison.

Use git difftool

git diff prints text directly in the terminal. git difftool asks Git to compare the same revisions, but open the comparison in an external program.

For example:

git difftool HEAD~1 HEAD
git difftool main...feature-branch
git difftool -- path/to/file.py

If a tool is configured, Git will launch it with temporary copies of the local and remote versions.

Configure a Preferred Tool

Some tools are known to Git by name. If yours is one of them, you can set it directly:

git config --global diff.tool meld
git config --global difftool.prompt false

The second setting disables the "launch tool for each file" prompt, which is convenient for day-to-day use.

You can inspect which tools Git knows about:

git difftool --tool-help

Configure Visual Studio Code as a Diff Tool

If you prefer VS Code, define the exact launch command. Git exposes the two file paths as $LOCAL and $REMOTE.

git config --global diff.tool vscode
git config --global difftool.vscode.cmd 'code --wait --diff "$LOCAL" "$REMOTE"'
git config --global difftool.prompt false

Now run:

git difftool HEAD~1 HEAD

VS Code opens a side-by-side diff and waits until you close the window before returning control to Git.

Use a One-Off Tool Without Changing Global Config

You do not need to commit to one viewer forever. You can override the configured tool per command:

git difftool --tool=meld main...feature-branch
git difftool --tool=vscode -- src/app.js

This is useful when you normally work in the terminal but want a graphical view for a large refactor.

Configure a Custom Tool

If Git does not recognize your preferred application by name, define a custom difftool command in your Git config.

1[diff]
2    tool = myviewer
3[difftool "myviewer"]
4    cmd = /Applications/MyDiffApp.app/Contents/MacOS/MyDiffApp "$LOCAL" "$REMOTE"
5[difftool]
6    prompt = false

You can place that in ~/.gitconfig or set it through git config --global.

Useful Variants

The same revision syntax from git diff works with git difftool:

git difftool
git difftool --cached
git difftool HEAD~3 HEAD -- src/server.ts

These commands compare:

• working tree versus index
• index versus last commit
• one commit range for only one path

That makes git difftool practical both for quick checks and for deeper review work.

Common Pitfalls

• Configuring diff.tool but then running git diff and expecting a GUI. Use git difftool.
• Forgetting --wait for editors like VS Code can make Git think the tool finished immediately.
• Omitting quotes around $LOCAL and $REMOTE can break paths that contain spaces.
• Setting difftool.prompt false globally is convenient, but some developers prefer the prompt for large changesets.
• Choosing a tool that is not installed on every machine can make shared setup docs confusing. Document platform differences clearly.

Summary

• Use git difftool when you want Git to open an external diff viewer.
• Set diff.tool to a supported tool name or define a custom command.
• For VS Code, code --wait --diff "$LOCAL" "$REMOTE" is a common setup.
• Use --tool=... for one-off comparisons without changing global config.
• Keep quoting and --wait correct so Git and the viewer stay in sync.