Mercurial Named Branches

Mercurial named branches are a “power user” technique that applies a persistent name to a branch of development. A named branch can be used to isolate a line of development that is expected to take days, weeks, or longer to complete. Isolation of such development on a named branch means that development on the “main” branch of the repository (which is, in fact, named default) can continue in parallel. Another use case for named branches is isolation of a line of development that will take time and may not prove to be useful in the end, in which case the branch can be marked as closed, and abandoned.

Examples of the use of named branches in the tools include:

There is a brief description of the key elements of working with named branches in the Mercurial docs, and a more narrative discussion in the Naming branches within a repository in the Mercurial - The Definitive Guide.

To see the active named branches in a repo use:

$ hg branches
default                     3099:c2c481bf14eb
refactor-nowcast-figures    3098:ec4ce3412411

To included closed branches in the list use hg branches --closed.

To create a new named branch use:

$ hg branch refactor-nowcast-figures

To see what branch you are presently on use:

$ hg branch

You can also start a named branch from an earlier stage of development by updating to a specific revision before creating the branch:

$ hg update -r 500
$ hg branch my-branch

Commits made on a branch other than default include the name of the branch in their metadata as you can see with commands like hg log, hg glog, hg log --graph, or hg tip:

changeset:   3097:fb2b10884a4f
branch:      refactor-nowcast-figures
tag:         tip
user:        Doug Latornell <djl@douglatornell.ca>
date:        Sun Mar 27 23:01:33 2016 -0700
summary:     Continue development of prototype nowcast figure module.

To switch between named branches use the hg update command with the branch name:

$ hg update default

Note

Your working copy must be clean (no uncommitted changes) before you can update to another branch.

It is almost always a good idea to regularly merge changes from the default branch into your named branch. Doing so means that when you finally merge your named branch back into the default branch the merge should be relatively small and manageable. To merge the default branch into your development branch use:

$ hg update refactor-nowcast-figures
$ hg merge default

Obviously, if the development your are doing in your named branch conflicts with the changes that have occurred in the default branch, you will have to resolve the merge conflicts.

When you have finished development on your named branch, either by merging into the default branch, or by abandoning it, you can chose it to remove it from the list of branches displayed by the hg branches command:

$ hg update refactor-nowcast-figures
$ hg commit --close-branch -m"Close refactor-nowcast-figures branch."
$ hg update default

If you merged your named branch into default (in contrast to abandoning it), do one more hg merge to capture the branch closure commit:

$ hg merge refactor-nowcast-figures

It is possible to avoid an explicit branch closure commit by including the --close-branch option on the final commit before you merge a named branch into default, but that requires rare prescience.

You can re-open a closed branch by updating to it:

$ hg update my-closed-branch

and subsequent commits will apply to the re-opened branch.