2.6. Merging bugfixes across branches

The most common case where you will want to use the merge command is when merging bugfixes in the stable branch (currently v1-7) into the default (unstable) branch. This is very simple in Mercurial; if we assume we’re in a working copy which is on the head of the default branch:

hg merge v1-7

Changes will be merged into your working copy along with parent metadata tracking the merge. If there are conflicts, you’ll have to resolve them in your working copy before you commit. Once you’ve done this and tested the merge, you should commit it. You don’t need to specify much detail in the merge commit (just Merged from v1-7 or similar) because the changeset metadata gives enough information to track which changesets are included in the merge.


Any team member can perform the merge (sinbad used to do it all the time under Subversion), but it’s important that you merge the entire branch as shown above and not just specifically merge your own changes (which is possible, but not covered here because it’s the wrong thing to do). Also, it’s advisable to push your changes promptly after committing the merge to minimise the chance of overlapping with anyone else doing the same thing.


Even on Windows, I strongly recommend using KDiff3 (included with TortoiseHg) to resolve conflicts and not WinMerge or TortoiseMerge. The reason is that when using a graphical diff tool, conflicts are handled in Mercurial by keeping separate files rather than embedding the "chevron markers" inside the main file. When Mercurial delegates the merge to the GUI tool, it assumes you resolved the problem when you exit - and the problem with WinMerge is that it doesn’t give you any warning if you exit without resolving the problem (often leaving you with a file which has not merged either of the conflicting changes into it, so you lose changes!). KDiff3 however warns you if you try to exit without resolving every conflict.


I strongly recommend merging on the command line as above, and not using TortoiseHg which can be extremely unintuitive for doing merges. In TortoiseHg you have to left-click to select the revision you want to merge changes into (so in this case, the tip of the default branch), then right-click the revision you want to merge changes from (in this case, the tip of the v1-7 branch), then select "Merge With…". It’s very manual and very error prone - if you get it backwards you will effectively switch your working copy to v1-7 and merge the default changes into it!! Very bad. The command-line is far simpler and less prone to manual error.