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,
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
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,
Examples of the use of named branches in the tools include:
- Development of v2.0 of the Salish Sea NEMO Command Processor to support NEMO-3.6 in the
- Separation of the nowcast system code from the SalishSeaTools Package into the SalishSeaNowcast Package in the
- Refactoring of the nowcast system web page results figures into a 1 figure per module architecture in the
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 log --graph,
or hg tip:
changeset: 3097:fb2b10884a4f branch: refactor-nowcast-figures tag: tip user: Doug Latornell <email@example.com> 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
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
if the development your are doing in your named branch conflicts with the changes that have occurred in the
you will have to resolve the merge conflicts.
When you have finished development on your named branch,
either by merging into the
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
(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
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.