{i} This page does not meet our wiki style guidelines. Please help improve this page by cleaning up its formatting.

Merge Tool Configuration

How to customize which merge tools Mercurial chooses.

1. Introduction

Mercurial delegates most non-trivial file-level merging operations to an external program, called a merge tool. In most installations, Mercurial will automatically search your system for the 'best' available tool, based on a set of known tools in its global configuration.

This tool choice can be extensively customized based on various properties like filename, binary data, running in a GUI, etc.

2. Defining a merge tool

To define a merge tool, add something like the following in .hgrc:

 [merge-tools]
 mymergetool.something = something

which will define mymergetool (the left hand side until the first dot). The option values defines the behaviour of the tool.

For each file changed in both parents Mercurial chooses a merge tool. The merge tool is chosen from the list of file pattern matches in the [merge-patterns] section followed by all tools sorted by decreasing priority order. The list is filtered for whether the executable (defaulting to mymergetool) can be found, whether it supports symlinks or binary files, and whether gui is available. To bypass the priority scheme and set the default tool directly, specify the merge tool in [ui] sections merge option. For backwards compatibility the tool hgmerge is implicitly added with lowest priority.

If the chosen merge tools premerge is True then an internal merge is attempted, and if it seems successful then the result it will silently be used without running the actual merge tool.

The merge tool is run with an argument list of args with the following variables expanded:

Example configuration:

 [merge-tools]
 mymergetool.priority = 100
 mymergetool.premerge = False
 mymergetool.args = $local $other $base -o $output
 myimgmerge =
 [merge-patterns]
 **.jpg = myimgmerge
 **.exe = internal:fail

Further tool options include:

 <tool>.args - the arguments to pass (defaults to $local $base $other)
 <tool>.executable - executable name or path (defaults to <tool>)
 <tool>.binary - supports binary files (False)
 <tool>.symlinks - supports symlinks (False)
 <tool>.gui - requires a GUI (False)
 <tool>.priority - priority of this tool (0)

3. Internal merge with conflict markers

Mercurial has a selection of "internal" tools for various purposes (ee merge-tools for full details). The most interesting of these is internal:merge, which provides a traditional merge with conflict markers. To set this as your default tool, simply add the following to you config:

[ui]
merge = internal:merge

This is not generally recommended as Mercurial gets no direct feedback when merges are successfully completed, and it's not terribly user-friendly compared to modern tools.

(!) When using internal:merge, you'll want to carefully read the help for the resolve command to avoid losing your merge work.

3.1. See also

3.2. Notes

In February 2008, Matt Mackall contributed this new merge tool configuration feature. This feature is available in version 1.0 (see WhatsNew).

3.2.1. Choosing internal merge with conflict markers

To have the internal merge with the conflict markers for example in TortoiseHg set

[ui]
merge = internal:merge

in Mercurial.ini.

3.2.2. Overriding merge.ui configuration from the command line

See How to keep "My" or "Their" files when doing merge for an example on how you can override merge configuration on the command line.


CategoryHowTo