Skip to content
Tutorials Center
My learning

Topics

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.

Terminal
git merge feature            # conflicts
git mergetool                # step through each conflicted file
git mergetool --tool=meld    # choose a tool once

Try it

Bash A custom tool resolves the conflict

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.

Bash The files the tool receives

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

Terminal
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. mergetool acts on paths that are unmerged in the index; it does nothing for a clean merge.
  • .orig files. By default each resolved file leaves name.orig behind. Set mergetool.keepBackup false or add *.orig to 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 $BASE is empty or absent and two-way tools show only local and remote.
  • Diff3 style. With merge.conflictStyle set to diff3 or zdiff3, the conflict markers inside $MERGED also 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 difftool uses the same configuration style for viewing differences. git rerere saves you from solving the same conflict twice.
  • Ours and theirs in a rebase are swapped: $LOCAL is the branch being rebased onto, $REMOTE is your commit being replayed.