|
|
We’ve now covered cloning a repository, making changes in a repository, and pulling or pushing changes from one repository into another. Our next step is merging changes from separate repositories.
Merging is a fundamental part of working with a distributed revision control tool.
Because merging is such a common thing to need to do, Mercurial makes it easy. Let’s walk through the process. We’ll begin by cloning yet another repository (see how often they spring up?) and making a change in it.
We should now have two copies of hello.c with different contents. The histories of the two repositories have also diverged, as illustrated in figure 3.1.
We already know that pulling changes from our my-hello repository will have no effect on the working directory.
However, the “hg pull” command says something about “heads”.
A head is a change that has no descendants, or children, as they’re also known. The tip revision is thus a head, because the newest revision in a repository doesn’t have any children, but a repository can contain more than one head.
In figure 3.2, you can see the effect of the pull from my-hello into my-new-hello. The history that was already present in my-new-hello is untouched, but a new revision has been added. By referring to figure 3.1, we can see that the changeset ID remains the same in the new repository, but the revision number has changed. (This, incidentally, is a fine example of why it’s not safe to use revision numbers when discussing changesets.) We can view the heads in a repository using the “hg heads” command.
What happens if we try to use the normal “hg update” command to update to the new tip?
Mercurial is telling us that the “hg update” command won’t do a merge; it won’t update the working directory when it thinks we might be wanting to do a merge, unless we force it to do so. Instead, we use the “hg merge” command to merge the two heads.
This updates the working directory so that it contains changes from both heads, which is reflected in both the output of “hg parents” and the contents of hello.c.
Whenever we’ve done a merge, “hg parents” will display two parents until we “hg commit” the results of the merge.
We now have a new tip revision; notice that it has both of our former heads as its parents. These are the same revisions that were previously displayed by “hg parents”.
In figure 3.3, you can see a representation of what happens to the working directory during the merge, and how this affects the repository when the commit happens. During the merge, the working directory has two parent changesets, and these become the parents of the new changeset.
Most merges are simple affairs, but sometimes you’ll find yourself merging changes where each modifies the same portions of the same files. Unless both modifications are identical, this results in a conflict, where you have to decide how to reconcile the different changes into something coherent.
Figure 3.4 illustrates an instance of two conflicting changes to a document. We started with a single version of the file; then we made some changes; while someone else made different changes to the same text. Our task in resolving the conflicting changes is to decide what the file should look like.
Mercurial doesn’t have a built-in facility for handling conflicts. Instead, it runs an external program called hgmerge. This is a shell script that is bundled with Mercurial; you can change it to behave however you please. What it does by default is try 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, the script tries a few different graphical merging tools.
It’s also possible to get Mercurial to run another program or script instead of hgmerge, by setting the HGMERGE environment variable to the name of your preferred program.
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:
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.
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 specialised file formats (generally XML).
In this example, we will reproduce the file modification history of figure 3.4 above. Let’s begin by creating a repository with a base version of our document.
We’ll clone the repository and make a change to the file.
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.)
Having created two different versions of the file, we’ll set up an environment suitable for running our merge.
In this example, I won’t use Mercurial’s normal hgmerge program to do the merge, because it would drop my nice automated example-running tool into a graphical user interface. Instead, I’ll set HGMERGE to tell Mercurial to use the non-interactive merge command. This is bundled with many Unix-like systems. If you’re following this example on your computer, don’t bother setting HGMERGE.
Because merge can’t resolve the conflicting changes, it leaves merge markers inside the file that has conflicts, indicating which lines have conflicts, and whether they came from our version of the file or theirs.
Mercurial can tell from the way merge exits that it wasn’t able to merge successfully, so it tells us what commands we’ll need to run if we want to redo the merging operation. This could be useful if, for example, we were running a graphical merge tool and quit because we were confused or realised we had made a mistake.
If automatic or manual merges fail, there’s nothing to prevent us from “fixing up” the affected files ourselves, and committing the results of our merge:
The process of merging changes as outlined above is straightforward, but requires running three commands in sequence.
In the case of the final commit, you also need to enter a commit message, which is almost always going to be a piece of uninteresting “boilerplate” text.
It would be nice to reduce the number of steps needed, if this were possible. Indeed, Mercurial is distributed with an extension called fetch that does just this.
Mercurial provides a flexible extension mechanism that lets people extend its functionality, while keeping the core of Mercurial small and easy to deal with. Some extensions add new commands that you can use from the command line, while others work “behind the scenes,” for example adding capabilities to the server.
The fetch extension adds a new command called, not surprisingly, “hg fetch”. This extension acts as a combination of “hg pull”, “hg update” and “hg merge”. It begins by pulling changes from another repository into the current repository. If it finds that the changes added a new head to the repository, it begins a merge, then commits the result of the merge with an automatically-generated commit message. If no new heads were added, it updates the working directory to the new tip changeset.
Enabling the fetch extension is easy. Edit your .hgrc, and either go to the [extensions] section or create an [extensions] section. Then add a line that simply reads “fetch ”.
(Normally, on the right-hand side of the “=” would appear the location of the extension, but since the fetch extension is in the standard distribution, Mercurial knows where to search for it.)
