Tutorial - Merging changes

In TutorialExport, we learned how to share a change with another person. But since (as of version 0.7) ["Import"] isn't functional enough to handle emailed merges correctly, we're going to demonstrate merging by pulling from another repository that has made an incompatible change.

First, we must create something to merge. Let's ["Clone"] the my-hello repository again:

$ cd ..
$ hg clone my-hello my-hello-desc

We are going to give hello.c a description in its comment section.

$ cd my-hello-desc
$ vi hello.c

Let's change the second line from this:

 * hello.c

to this:

 * hello.c - hello, world

Let's save and quit the editor, and ["Commit"] our change. This time, we save some time by using the -m option to the commit command, to spare us from being dropped into an editor:

$ hg commit -m "Add description of hello.c"

At this point, we have made one change to hello.c in the my-hello-new-output ["Repository"], and another change to hello.c in the my-hello-desc ["Repository"]. How do we merge these two diverging lines of development? Will there be a problem when we want to pull from one into the other?

This works just fine. While still in my-hello-desc, let's ["Pull"] the changes from my-hello-new-output and see what happens:

$ hg pull ../my-hello-new-output
pulling from ../my-hello-new-output
searching for changes
adding changesets
adding manifests
adding file changes
added 1 changesets with 1 changes to 1 files (+1 heads)
(run 'hg heads' to see heads, 'hg merge' to merge)

This looks just like the output of pull from TutorialShareChange! So all we have to do is an ["Update"] now, right?

$ hg update
abort: update spans branches, use 'hg merge' or 'hg update -C' to lose changes

Nope. Something has happened. ["Mercurial"] is telling us that we must ["Merge"] the changes that we made in each ["Repository"]. This sounds painful, right? It's actually very easy. Let's follow the instructions of the last line of output:

$ hg merge
merging hello.c
0 files updated, 1 files merged, 0 files removed, 0 files unresolved
(branch merge, don't forget to commit)

(Note for Windows users: ["Mercurial"] is missing a merge program, if you get an error like hgmerge is not recognized as an internal or external command. See MergeProgram for information on how to fix this.)

That's all there is to it! ["Mercurial"] was able to handle the merge automatically for you, by calling under the covers the hgmerge script (or whatever is your MergeProgram). Depending on your environment, the hgmerge may call a graphical merge resolver tool. If we look at hello.c, we find that it contains both the change from my-hello-new-output and the change from my-hello-desc.

(Note: before Mercurial version 0.9, hg update -m should have been used in place of hg merge).

When working with changes made by other people, this is the kind of merge you will end up performing most of the time. Don't forget to commit this change to the repository, as suggested on the last line of the output from hg merge:

$ hg commit -m "Merged changes from my-hello-new-output"

There shouldn't be any output from this command.

Let us continue on, however, and learn how to deal with situations where conflicting changes have been made in TutorialConflict.