git mergetool: Configuring External Merge Tools

While IDEs like VS Code and IntelliJ have their own built-in conflict resolution features (previous lesson), Git also provides a dedicated, tool-agnostic command — `git mergetool` — that launches whatever external merge tool you've configured, directly from the command line, for any conflicted file. This gives you flexibility to use a dedicated diff/merge application even if your primary editor doesn't have built-in conflict resolution, or if you simply prefer a specialized tool.

Learning Objectives

Configure a specific external merge tool using git config merge.tool.
Launch the configured tool for all conflicted files using git mergetool.
Understand common merge tool options, including using VS Code itself as a mergetool.
Recognize the .orig backup files git mergetool creates, and how to clean them up.

Key Terms to Know Before Learning git mergetool

git mergetool: A command that launches a configured external tool to help resolve merge conflicts, one file at a time.
merge.tool: The Git configuration key specifying which external tool git mergetool should launch.
mergetool.<name>.cmd: A configuration key defining the exact command Git should run to launch a custom, unlisted merge tool.
.orig files: Backup copies of conflicted files, automatically created by git mergetool before resolution, preserving the original conflicted state.

How git mergetool Actually Works

Before using `git mergetool`, you need to tell Git which external tool to launch. This is configured with the same `git config` mechanism from Module 1, using the `merge.tool` key:

```
git config --global merge.tool vscode
```

Git ships with built-in support for several popular tools by name — including `vscode`, `kdiff3`, `meld`, `opendiff`, `p4merge`, and others — meaning for many common tools, this single line is all the configuration needed. For VS Code specifically, you'd also typically configure the exact command Git uses to launch it:

```
git config --global mergetool.vscode.cmd 'code --wait $MERGED'
```

Once configured, whenever you have unresolved conflicts after a `git merge`, running:

```
git mergetool
```

launches your configured tool once for each conflicted file in sequence, letting you resolve each one using that application's interface (which might be a three-pane view, inline buttons, or another layout depending on the specific tool). After you resolve and save a file within the tool and close it, Git automatically moves on to the next conflicted file, if any remain.

An important detail: by default, `git mergetool` creates backup copies of each conflicted file with a `.orig` extension (e.g., `app.js.orig`) before resolution, preserving the original conflicted state in case you need to reference it later. These backup files are **not** automatically deleted, and are **not** part of your Git history — they're just loose files sitting in your working directory afterward. Many developers clean these up after confirming a successful resolution:

```
find . -name "*.orig" -delete
```

Or, to avoid this cleanup step entirely, you can disable the backup creation going forward:

```
git config --global mergetool.keepBackup false
```

Once every conflicted file has been resolved through `git mergetool`, the remaining steps are identical to manual resolution: verify with `git status` that no unresolved conflicts remain, and run `git commit` to finalize the merge.

It's worth understanding when `git mergetool` is genuinely useful versus when it's unnecessary overhead: if your primary editor (like VS Code or IntelliJ) already has strong built-in conflict resolution, as covered in the previous lesson, you may rarely need `git mergetool` at all — it's most valuable for developers who prefer a dedicated, specialized diff/merge application (like KDiff3 or Beyond Compare) separate from their regular code editor, or who work primarily from the command line without a full IDE.

git mergetool: Visual Walkthrough

Draw a flow: 'git config --global merge.tool <tool-name> (one-time setup)' → 'Conflict occurs during git merge' → 'Run: git mergetool' → 'External tool launches automatically for EACH conflicted file in sequence' → 'Resolve and save within the tool, close it' → 'Git moves to next conflicted file (if any)' → 'git status confirms all resolved' → 'git commit completes the merge'. Add a side note box: '.orig backup files are created by default — clean up with find . -name "*.orig" -delete, or disable via mergetool.keepBackup false.'

git mergetool: Quick Reference Table

Configuration	Purpose	Example
merge.tool	Specifies which external tool git mergetool should launch	git config --global merge.tool vscode
mergetool.<name>.cmd	Defines the exact launch command for a specific tool	git config --global mergetool.vscode.cmd 'code --wait $MERGED'
mergetool.keepBackup	Controls whether .orig backup files are kept after resolution	git config --global mergetool.keepBackup false

git mergetool: Command Syntax and Examples

# One-time setup: configure VS Code as your merge tool
git config --global merge.tool vscode
git config --global mergetool.vscode.cmd 'code --wait $MERGED'

# When a conflict occurs, launch the configured tool for each conflicted file
git mergetool

# After resolving everything, confirm no conflicts remain
git status

# Clean up leftover .orig backup files
find . -name "*.orig" -delete

# Optionally, disable .orig backups going forward
git config --global mergetool.keepBackup false

# Complete the merge
git commit

Breaking Down the git mergetool Example

The first two lines are a one-time setup, telling Git to use VS Code specifically as the merge tool, and specifying the exact command (`code --wait $MERGED`) used to launch it. Running `git mergetool` afterward, during an actual conflict, opens VS Code (or whichever tool was configured) automatically for each conflicted file. After resolving everything within the tool, `git status` confirms the conflict is fully resolved, and the `find` command cleans up any leftover `.orig` backup files that `git mergetool` created by default. Disabling `keepBackup` avoids needing this cleanup step in future merges. Finally, `git commit` completes the merge, exactly as in manual or IDE-native resolution.

How git mergetool Is Used on Real Engineering Teams

Developers who work heavily from the terminal, without a full-featured IDE open, often rely on git mergetool combined with a lightweight dedicated tool like Meld or vimdiff for conflict resolution.
Some engineering teams standardize on a specific configured mergetool (like KDiff3 or Beyond Compare) as part of onboarding, ensuring everyone resolves conflicts using the same familiar interface regardless of their personal code editor choice.
Enterprise environments with strict tooling requirements sometimes mandate specific approved diff/merge tools for compliance or licensing reasons, configured centrally via git mergetool settings.
Automated .orig cleanup scripts are a common addition to project-level .gitignore files (ignoring *.orig entirely) specifically to avoid these leftover backup files ever being accidentally committed.

git mergetool Interview Questions and Answers

Q1. What does git mergetool do, and how do you configure which tool it launches?

git mergetool launches a configured external application to help resolve merge conflicts, one conflicted file at a time. You configure which tool it uses via git config --global merge.tool <name>, with Git providing built-in support for several popular tools by name, such as vscode, kdiff3, and meld.

Q2. What are .orig files, and why do they appear after using git mergetool?

They are backup copies of each conflicted file, created automatically by git mergetool by default, preserving the original conflicted content before resolution. They are not part of Git's tracked history and need to be manually cleaned up, or their creation can be disabled entirely with git config --global mergetool.keepBackup false.

Q3. After resolving all conflicts using git mergetool, what steps remain to finish the merge?

Exactly the same as manual resolution: verify with git status that no conflicts remain, and then run git commit to finalize the merge, since git mergetool only handles the resolution step itself, not staging or committing.

git mergetool Quiz: Test Your Understanding

1. Which configuration key specifies which external tool git mergetool should launch?

core.editor
merge.tool
diff.tool
user.mergeapp

Answer: B. merge.tool

Explanation: merge.tool is the specific configuration key used to tell Git which external application to launch when git mergetool is run.

2. What are .orig files created by git mergetool?

Compressed backups of the entire repository
Backup copies of each conflicted file's original content before resolution
A log of every command used during the merge
Files required for the merge to complete successfully

Answer: B. Backup copies of each conflicted file's original content before resolution

Explanation: .orig files preserve a copy of the file exactly as it was in its conflicted state, created by default before git mergetool helps you resolve it, and are not part of Git's tracked history.

3. After using git mergetool to resolve all conflicts, what command is still needed to finalize the merge?

git mergetool --finish
git commit
git branch --complete
No further command is needed

Answer: B. git commit

Explanation: git mergetool only handles resolving the conflicts within each file; git commit (after confirming resolution with git status) is still required to actually complete the merge, just as with manual resolution.

git mergetool: Common Mistakes Beginners Make

Forgetting to configure merge.tool before running git mergetool, resulting in Git prompting for a tool choice or failing to launch anything.
Leaving .orig backup files scattered throughout the project and accidentally committing them, since they aren't ignored by default.
Assuming git mergetool automatically stages and commits resolved files — it only handles the resolution step itself.
Not realizing IDEs like VS Code and IntelliJ often already have adequate built-in conflict resolution, making git mergetool an optional convenience rather than a strict requirement.

git mergetool: Exam-Ready Quick Notes

git config --global merge.tool <name>: configures which external tool git mergetool launches.
git mergetool: launches the configured tool for each conflicted file in sequence.
.orig backup files are created by default; clean up manually or disable with mergetool.keepBackup false.
git add/commit are still required after resolution — git mergetool only handles the resolving step.

git mergetool: Key Takeaways

git mergetool provides a flexible, tool-agnostic way to launch any configured external application for resolving conflicts directly from the command line.
Configuration (merge.tool, and sometimes a custom command) is a one-time setup step that then applies to every future conflict.
Regardless of which tool resolves the conflict, git add/commit (or their equivalent completion within git mergetool's flow) are still required to finalize the merge.

Frequently Asked Questions About git mergetool

Q1. What is git mergetool used for?

It launches an external application you've configured to help you resolve merge conflicts, opening it automatically for each conflicted file so you can decide on the correct content using that tool's interface.

Q2. How do I set up git mergetool to use a specific application?

Run git config --global merge.tool <name>, using a name Git recognizes (like vscode, kdiff3, or meld) for built-in support, or configure a custom command with mergetool.<name>.cmd for tools Git doesn't know about by default.

Q3. What are the .orig files that appear after using git mergetool?

They're automatic backup copies of each file's original conflicted content, created by default before resolution. They aren't tracked by Git and can be safely deleted once you've confirmed your resolution is correct, or you can disable their creation with mergetool.keepBackup false.

Q4. Do I still need to commit after resolving conflicts with git mergetool?

Yes. git mergetool only handles the resolution of each file's content — you still need to verify with git status that everything is resolved, and run git commit to actually finalize the merge.

Q5. Do I need to use git mergetool if my editor already has built-in conflict resolution?

Not necessarily. If your editor (like VS Code or IntelliJ) already provides adequate conflict resolution tools, git mergetool is simply an optional alternative — most useful for developers who prefer a dedicated, specialized diff/merge application or who work mainly from the command line.

Summary

`git mergetool` launches a configured external application to help resolve merge conflicts, one conflicted file at a time, offering a command-line-friendly alternative to an IDE's built-in conflict resolution. It's configured via `git config --global merge.tool <name>`, with built-in support for many popular tools (vscode, kdiff3, meld, and others), and can be customized further with a specific launch command via `mergetool.<name>.cmd`. By default, it creates `.orig` backup files preserving each conflicted file's original state, which can be manually cleaned up or disabled entirely with `mergetool.keepBackup false`. Regardless of which tool is used, resolving conflicts through `git mergetool` still requires the same final `git status` verification and `git commit` to complete the merge.