Setting up Mercurial for resolving merge conflicts

Before using Mercurial on production sources you should make sure you understand not only what merging does, but also that your merge tool is correctly set up in the unusual case of a line-by-line merge conflict. Let's make some dummy repositories to test a merge conflict.

We will use hg clone -r REV to simulate another person cloning a repository before some further changes were made. You could equivalently switch back and forth between the repositories, but clone -r will be helpful in retrying the merge.

$ hg init hgtest-how-to-merge
$ cd hgtest-how-to-merge
$ echo one > f
$ hg ci -A -m one
adding f
$ echo two > f
$ hg ci -m two
$ hg log
changeset:   1:de9c1703a8d3
tag:         tip
user:        ....
date:        ....
summary:     two

changeset:   0:58d574e6ba6e
user:        ....
date:        ....
summary:     one

$ hg clone -r 0 . dupe
requesting all changes
adding changesets
adding manifests
adding file changes
added 1 changesets with 1 changes to 1 files
1 files updated, 0 files merged, 0 files removed, 0 files unresolved
$ cd dupe
$ echo three > f
$ hg ci -m three
$ hg log
changeset:   1:04d4360ce505
tag:         tip
user:        ....
date:        ....
summary:     three

changeset:   0:58d574e6ba6e
user:        ....
date:        ....
summary:     one

Now the second user, in the dupe repository clone, has committed changes against revision 58d574e6ba6e, effectively creating a new branch. In this case we have intentionally committed conflicting changes to the same file. When the second user tries to merge in changes from the first, Mercurial will look for a graphical merge tool and try to launch it. If your Hg installation is configured correctly, this tool will be found, and you will be able to resolve the merge and save:

$ hg fetch ..
pulling from ..
searching for changes
adding changesets
adding manifests
adding file changes
added 1 changesets with 1 changes to 1 files (+1 heads)
merging with new head 2:de9c1703a8d3
merging f
0 files updated, 1 files merged, 0 files removed, 0 files unresolved
new changeset 3:2ac5c85658f0 merges remote changes with local
$ cat f
two and a half

Here the merge tool has shown us that two parties changed one to both two and three and we have resolved this by saying it should really be two and a half.

You can use hg glog to see the result graphically. Note that while changeset IDs (the long hex hashes) stay the same, sequence numbers are different from the original repository: 1 was pulled to this clone as 2 though it is still identified as de9c1703a8d3.

$ hg glog
@    changeset:   3:2ac5c85658f0
|\   tag:         tip
| |  parent:      1:04d4360ce505
| |  parent:      2:de9c1703a8d3
| |  user:        ....
| |  date:        ....
| |  summary:     Automated merge with file:/tmp/hgtest-how-to-merge
| |
| o  changeset:   2:de9c1703a8d3
| |  parent:      0:58d574e6ba6e
| |  user:        ....
| |  date:        ....
| |  summary:     two
| |
o |  changeset:   1:04d4360ce505
|/   user:        ....
|    date:        ....
|    summary:     three
|
o  changeset:   0:58d574e6ba6e
   user:        ....
   date:        ....
   summary:     one

If you found any problems with your merge tool configuration, try to fix it now according to Mercurial documentation. Then you can easily rerun the test:

$ cd ..
$ hg clone -r 0 . dupe2
requesting all changes
adding changesets
adding manifests
adding file changes
added 1 changesets with 1 changes to 1 files
1 files updated, 0 files merged, 0 files removed, 0 files unresolved
$ cd dupe2
$ echo three > f
$ hg ci -m three

and try the merge again.

Unix users who prefer not to use graphical merge tools at all can choose to just get CVS-style conflict markers. In this case you will need to edit the conflicted files, manually resolve the conflicts, and commit the merge when done. You will need the command merge in your path (many systems put this in a package called rcs). And in your ~/.profile or similar, add export HGMERGE=merge to use this simple tool. Here is an example of the result:

$ HGMERGE=merge hg fetch ..
pulling from ..
searching for changes
adding changesets
adding manifests
adding file changes
added 1 changesets with 1 changes to 1 files (+1 heads)
merging with new head 2:de9c1703a8d3
merging f
merge: warning: conflicts during merge
merging f failed!
0 files updated, 0 files merged, 0 files removed, 1 files unresolved
There are unresolved merges, you can redo the full merge using:
  hg update -C 1
  hg merge 2
$ cat f
<<<<<<< /tmp/hgtest-how-to-merge/dupe2/f
three
=======
two
>>>>>>> /tmp/f~other.6OGVvm
$ echo 'two and a half' > f
$ hg di
diff --git a/f b/f
--- a/f
+++ b/f
@@ -1,1 +1,1 @@ three
-three
+two and a half
$ hg ci -m merged
$ hg glog
@    changeset:   3:081a22ed714b
|\   tag:         tip
| |  parent:      1:6b06aa95da85
| |  parent:      2:de9c1703a8d3
| |  user:        ....
| |  date:        ....
| |  summary:     merged
| |
| o  changeset:   2:de9c1703a8d3
| |  parent:      0:58d574e6ba6e
| |  user:        ....
| |  date:        ....
| |  summary:     two
| |
o |  changeset:   1:6b06aa95da85
|/   user:        ....
|    date:        ....
|    summary:     three
|
o  changeset:   0:58d574e6ba6e
   user:        ....
   date:        ....
   summary:     one

You may also want to check out the Mercurial tutorial on merge conflicts.