Heaven of Mergurial

The previous post about merging with named branches in mercurial was reposted at dzone. Daniel Neugebauer commented there that he wouldn’t use the named branch feature for every small issue instead he suggested to do the merging directly within the same repository and for bigger changes he would use a ‘clone per issue’. Although Fabrizio Giudici sayed that ‘branch per issue’ works really well in practise. Get his introduction!

And here I’ll quote python.org which compares clone vs. branch per issue:

Mercurial has two basic ways of using branches: cloned branches, where each branch is kept in a separate repository, and named branches, where each revision keeps metadata to note on which branch it belongs. The former makes it easier to distinguish branches, at the expense of requiring more disk space on the client. The latter makes it a little easier to switch between branches, but often has somewhat unintuitive results for people (though this has been getting better in recent versions of Mercurial).

The current proposal is to use named branches for release branches and adopt cloned branches for feature branches […]

Differences between named branches and cloned branches:

  • Tags in a different (maintenance) clone aren’t available in the local clone
  • Clones with named branches will be larger, since they contain more data

The Mercurial book discourages the use of named branches, but it is, in this respect, somewhat outdated. Named branches have gotten much easier to use since that comment was written, due to improvements in hg.

So, think what you want šŸ˜‰

Here are the steps to do a merge from a cloned repository (clone per issue). Which is the recommended stragety for bigger changes. This merging-strategy is also covered in the official hg book.

  1. The working directory is:

    Now commit the last changes.

  2. cd ..;hg clone -r <oldrevisionnumber> app/ app-clone/
  3. cd app-clone

    DO CHANGES (add, edit, rename, delete files)

  4. hg commit -m "FIXED issueXY"
  5. cd ../app;
    hg pull ../app-clone

    Now your working copy with the folder app/ contains 2 heads. This can be fixed easily via:

  6. hg merge
  7. hg commit -m "merged fix of issueXY into development sources"

Although this strategy needs one or two more commands it is also very clear and logically. Here is a tip from Daniel:

You can also search the history by “hg log -k <keyword>”, so if you use prefixed commit messages like “ISSUE123: …” you could find changesets belonging to that issue almost as easy as using a named branch.

And finally here are the steps to do a merge directly within the repository (direct merge), recommended for smaller changes only:

  1. Working in you current repository at

    and commit the last changes

  2. hg update -C <oldrevisionnumber>
  3. DO CHANGES (add, edit, rename, delete files)
  4. hg commit -m "FIXED issueXY"

    now hg says something about that a new head was created. Try

    hg heads

    to see that the previous commit created a new head in the repository. A

    hg update

    would fail now. But the following command resolves that ‘problem’ easily:

  5. hg merge

    The working directory will now contain changes of both commits/heads!

  6. Do not forget:
    hg commit -m "merged fix of issueXY into development sources"

    Now the command

    hg heads

    only contains one head

So only 5 easy steps for a quick merge!


All three strategies: “direct merge”, “clone per issue” and “branch per issue” are logically and easy to remember. Nice! Personally I prefer named branches. That page and this question could show its (dis)advantages.

BTW: for people looking for a git vs. hg site. Here are is one link.


One thought on “Heaven of Mergurial

  1. Pingback: Mercurial Will Beam You in The Heaven of Merging « Find Time for the Karussell

Comments are closed.