Introduction

git difftool is useful when you want to inspect conflicting changes visually, but it is not the tool that actually resolves the conflict state in Git. The practical workflow is usually: use difftool to understand the differences, then use mergetool or a normal editor to produce the final resolved file.

Configure a visual tool once

First, tell Git which external tool to use. meld, kdiff3, Beyond Compare, and vimdiff are common choices.

1git config --global diff.tool meld
2git config --global merge.tool meld
3git config --global difftool.prompt false
4git config --global mergetool.prompt false

Once configured, the same UI can often be used both for inspecting differences and for resolving conflicts.

Use difftool to inspect the two sides

During an active merge conflict, Git records the current branch state in HEAD and the incoming branch state in MERGE_HEAD. You can compare them for a file like this:

git difftool HEAD MERGE_HEAD -- app/settings.py

That gives you a clean side-by-side comparison of the two versions. This is often easier to reason about than reading conflict markers directly in the file.

You can also list unresolved files first:

git diff --name-only --diff-filter=U

That helps you choose which file to inspect next.

Use mergetool or a normal editor to resolve

Understanding the difference is only half the job. To actually resolve the conflict, you still need to edit the file and stage it.

A merge-tool flow looks like this:

git mergetool app/settings.py
git add app/settings.py
git commit

You can also edit the file yourself if you prefer. The key is that Git considers the conflict resolved only after the file is edited into a final form and staged.

A useful pre-merge workflow

git difftool is also valuable before you start the merge. If you compare the branches first, you can see where conflicts are likely to appear.

git difftool --dir-diff main...feature/login

Directory diff mode is useful when many files changed and you want a broader visual overview before touching the merge itself.

That often makes the actual conflict resolution faster because you already understand the shape of the branch differences.

Know the limits of difftool

difftool is for comparison, not state transition. It does not by itself clear the merge conflict in Git. Even if the external tool lets you inspect both sides nicely, Git still needs the resolved file staged afterward.

That is why difftool and mergetool should be thought of as complementary:

• 'difftool explains the conflict'
• 'mergetool or manual editing resolves it'

Common Pitfalls

The biggest pitfall is expecting git difftool to mark a conflict resolved. It does not. You must still edit the file, git add it, and complete the merge.

Another issue is using MERGE_HEAD when there is no active merge in progress. That reference exists only during an actual merge conflict.

It is also easy to forget that your external tool must be installed and reachable on the system. Git configuration alone is not enough if the tool binary is missing.

Finally, do not rely entirely on a GUI if the file still contains semantic decisions you need to make manually. A merge tool helps, but it does not decide the final content for you.

Summary

• Use git difftool to inspect conflicting changes visually.
• Compare HEAD and MERGE_HEAD during an active merge.
• Use git mergetool or a normal editor to produce the final resolved file.
• Always stage the resolved file with git add.
• Think of difftool as a comparison aid, not as the conflict-resolution step itself.