Mercurial_ The Definitive Guide - Bryan O'Sullivan [23]
Mercurial doesn’t have a built-in facility for handling conflicts. Instead, it runs an external program, usually one that displays some kind of graphical conflict resolution interface. By default, Mercurial tries to find one of several different merging tools that are likely to be installed on your system. It first tries a few fully automatic merging tools; if these don’t succeed (because the resolution process requires human guidance) or aren’t present, it tries a few different graphical merging tools.
It’s also possible to get Mercurial to run a specific program or script by setting the HGMERGE environment variable to the name of your preferred program.
Using a Graphical Merge Tool
My preferred graphical merge tool is kdiff3, which I’ll use to describe the features that are common to graphical file merging tools. You can see a screenshot of kdiff3 in action in Figure 3-5. The kind of merge it is performing is called a three-way merge, because there are three different versions of the file of interest to us. The tool thus splits the upper portion of the window into three panes:
At the left is the base version of the file, i.e., the most recent version from which the two versions we’re trying to merge are descended.
In the middle is “our” version of the file, with the contents that we modified.
On the right is “their” version of the file, the one from the changeset that we’re trying to merge with.
In the pane below these is the current result of the merge. Our task is to replace all of the red text, which indicates unresolved conflicts, with some sensible merger of the “ours” and “theirs” versions of the file.
All four of these panes are locked together; if we scroll vertically or horizontally in any of them, the others are updated to display the corresponding sections of their respective files.
Figure 3-5. Using kdiff3 to merge versions of a file
For each conflicting portion of the file, we can choose to resolve the conflict using some combination of text from the base version, ours, or theirs. We can also manually edit the merged file at any time, in case we need to make further modifications.
There are many file merging tools available, too many to cover here. They vary in which platforms they are available for, and in their particular strengths and weaknesses. Most are tuned for merging files containing plain text, while a few are aimed at specialized file formats (generally XML).
A Worked Example
In this example, we will reproduce the file modification history of Figure 3-4. Let’s begin by creating a repository with a base version of our document:
$ cat > letter.txt < > I am Mariam Abacha, the wife of former > Nigerian dictator Sani Abacha. > EOF $ hg add letter.txt $ hg commit -m '419 scam, first draft' We’ll clone the repository and make a change to the file: $ cd .. $ hg clone scam scam-cousin updating working directory 1 files updated, 0 files merged, 0 files removed, 0 files unresolved $ cd scam-cousin $ cat > letter.txt < > I am Shehu Musa Abacha, cousin to the former > Nigerian dictator Sani Abacha. > EOF $ hg commit -m '419 scam, with cousin' And another clone, to simulate someone else making a change to the file. (This hints at the idea that it’s not all that unusual to merge with yourself when you isolate tasks in separate repositories, and indeed to find and resolve conflicts while doing so.) $ cd .. $ hg clone scam scam-son updating working directory 1 files updated, 0 files merged, 0 files removed, 0 files unresolved $ cd scam-son $ cat > letter.txt < > I am Alhaji Abba Abacha, son of the former > Nigerian dictator Sani Abacha. > EOF $ hg commit -m '419 scam, with son' Having created two different versions of the file, we’ll set up an environment suitable for running our merge: $ cd .. $ hg clone scam-cousin scam-merge updating working directory 1 files updated, 0 files merged, 0 files removed, 0 files unresolved