Git Reference ยท Merging and Rebasing
git mergetool command
Reference for git mergetool: launch a graphical or custom tool for each conflicted file, define your own tool, and control backups, prompts and the base/local/remote files.
git mergetool runs a merge-resolution program on every file that still has conflicts after a failed merge, rebase, cherry-pick or stash pop. For each file Git writes out the pieces the program needs, starts it, waits, and on success marks the file as resolved with git add.
Git does not ship an editor of its own for this. It knows how to start dozens of tools (vimdiff, meld, kdiff3, VS Code, Beyond Compare and others) and lets you define your own command in the configuration. The tool receives four files: the common ancestor, your version, their version, and the output file to write.
git merge feature # conflicts git mergetool # step through each conflicted file git mergetool --tool=meld # choose a tool once
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.
Syntax
git mergetool [--tool=<tool>] [--no-prompt | --prompt] [-g | --gui] [-O<orderfile>] [<file>...] git mergetool --tool-help
| Name | Description |
|---|---|
--tool=<tool> |
Use this tool instead of merge.tool. The name is a built-in tool or one defined as mergetool.<tool>.cmd. |
-g, --gui |
Use merge.guitool (or fall back to merge.tool). |
--no-prompt, -y |
Do not ask "Hit return to start merge resolution tool" before each file. |
--prompt |
Always ask, overriding mergetool.prompt. |
-O<orderfile> |
Process files in the order given by the file. |
--tool-help |
List the tools Git knows and which ones are available on this machine. |
<file>... |
Only resolve these conflicted paths. |
Variables for custom commands: $BASE (common ancestor), $LOCAL (your side), $REMOTE (their side), $MERGED (the file to write). They are temporary files next to the conflicted file. Inside a cmd string they are shell variables, not environment variables, so hand them to your script as arguments.
| Configuration | Meaning |
|---|---|
merge.tool, merge.guitool |
Default tool, and the one for --gui. |
mergetool.<tool>.path |
Where the tool's executable is. |
mergetool.<tool>.cmd |
Shell command for a custom tool. |
mergetool.<tool>.trustExitCode |
Believe the tool's exit status instead of checking whether $MERGED changed. |
mergetool.keepBackup |
Keep the .orig file with the conflict markers (default true). |
mergetool.keepTemporaries |
Keep the _BASE_, _LOCAL_, _REMOTE_ temporaries. |
mergetool.prompt |
Ask before each file (default true). |
mergetool.hideResolved |
Pre-resolve the non-conflicting parts of the file given to the tool. |
mergetool.writeToTemp |
Create temporaries in a temp directory instead of beside the file. |
Errors and edge cases: with no conflicts Git prints No files need merging. If the tool exits non-zero (with trustExitCode) or leaves the file unchanged, Git asks whether the merge was successful and leaves the file unresolved if you say no.
Usage notes
- Conflicts only.
mergetoolacts on paths that are unmerged in the index; it does nothing for a clean merge. .origfiles. By default each resolved file leavesname.origbehind. Setmergetool.keepBackup falseor add*.origto your ignore file.- Deleted and renamed conflicts. For modify/delete conflicts Git asks which version to keep ("Use (m)odified or (d)eleted file"). The tool is only used for content conflicts.
- Base can be missing. For add/add conflicts there is no ancestor, so
$BASEis empty or absent and two-way tools show only local and remote. - Diff3 style. With
merge.conflictStyleset todiff3orzdiff3, the conflict markers inside$MERGEDalso show the base text, which many tools make use of. - Stage the result yourself if you skip the tool. After editing by hand use
git add <file>. The tool is a convenience, not a requirement. - Related tools.
git difftooluses the same configuration style for viewing differences.git rereresaves you from solving the same conflict twice. - Ours and theirs in a rebase are swapped:
$LOCALis the branch being rebased onto,$REMOTEis your commit being replayed.