Merge Program
A merge program combines two different versions of a file into a merged file.
Usually, the program tries to do so automatically, by combining all the non-overlapping changes that occurred separately in the two different evolutions of the same initial base file. Furthermore, some interactive merge programs make it easier to manually resolve conflicting merges, either in a graphical way, or by inserting some conflict markers.
It should be emphasized that Mercurial by itself doesn't attempt to do a merge at the file level, neither does it make any attempt to resolve the conflicts.
Contents
How Mercurial decides which merge program to use
If the HGMERGE environment variable is present, it is used.
Otherwise, if the filename of the file to be merged matches any of the patterns in the merge-patterns configuration section, then the corresponding merge tool is used. (See MergeToolConfiguration for details.)
Otherwise, if the ui.merge config setting is set, that is used. (The next section explains how to configure this.)
Otherwise, if any merge tools are present in the merge-tools configuration section, and any of the tools can be found on the system, the priority settings are used to determine which one to use. (MergeToolConfiguration explains how to configure this.)
Otherwise, if a program named hgmerge exists on the system, that is used.
Otherwise, if the file to be merged is not binary and is not a symlink, then internal:merge is used.
- Otherwise, the merge fails.
However: after selecting a merge program, Mercurial will usually attempt to merge the files using a simple merge algorithm first, to see if they can be merged without conflicts. Only if there are conflicting changes will hg actually execute the merge program. (If the file to be merged is binary or a symlink, then hg doesn't bother with the simple merge algorithm. If the selected merge tool is internal:fail, internal:local, or internal:other, then hg skips the simple merge algorithm, as the user has specifically requested that no merging take place.)
Before Mercurial 1.0, a script named hgmerge was installed by default. As of Mercurial 1.0, hgmerge is no longer installed (and it should not be distributed with Mercurial), but hg still uses it, if it's present on the system and no other merge tools are configured (see hgmerge)
Choosing and configuring a merge program
Some merge programs include:
diff3 - standard on most Unix/Linux installs, available from GnuWin32 for Windows.
tkdiff - known to work under Windows
kdiff3 - also works under Windows
gpyfm - GTK based file merge tool, from OpenSolaris project
TortoiseMerge - for Windows, part of TortoiseSVN
WinMerge - Windows only, as the name suggests.
SourceGear DiffMerge - works on Windows, OS X and Linux (WARNING: It always returns an ERRORLEVEL of 0 forcing Mercurial to merge, even when you have not solved the conflicts.).
DirDiff - a very nice Vim plugin
Emacs thanks to a little wrapper script to spawn ediff
FileMerge - Native Mac OS X file merging application.
Changes - alternative native Mac OS X file merging application. (proprietary)
Manually from within your favorite editor, thanks to a little wrapper script around GNU the diff3(1) utility
If you have a preferred merge program, you can set the merge entry in the ui section of your hgrc file.
[ui] merge = your-merge-program
In Mercurial 1.0 you can add the following to .hgrc:
[merge-tools] kdiff3.args = $base $local $other -o $output
FileMerge on Mac OS X
To configure merge to use FileMerge on Mac OS X, create a file called "opendiff-merge" with the following contents:
#!/bin/sh # opendiff returns immediately, without waiting for FileMerge to exit. # Piping the output makes opendiff wait for FileMerge. opendiff $1 $3 -merge $1 -ancestor $2 | cat
Save this file into your shell's default path ($PATH). Because this is a shell script, you need to be sure it has execution permissions:
chmod +x opendiff-merge
Next look in your home directory for the following file ".hgrc". If it does not exist, create it. If it does exist, add the following to it:
[ui] merge = opendiff-merge
The command "hg merge" will now use FileMerge to resolve it's conflicts.
1. Better way in Mercurial 1.0
Use instead the same opendiff-w script as described in ExtdiffExtension:
#!/bin/sh # opendiff returns immediately, without waiting for FileMerge to exit. # Piping the output makes opendiff wait for FileMerge. opendiff "$@" | cat
Add the following to your .hgrc file:
[merge-tools] filemerge.executable = opendiff-w filemerge.args = $local $other -ancestor $base -merge $output