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:
- Development of v2.0 of the Salish Sea NEMO Command Processor to support NEMO-3.6 in the SalishSeaCmd-3.6 branch
- Separation of the nowcast system code from the SalishSeaTools Package into the SalishSeaNowcast Package in the SalishSeaNowcast branch
- Refactoring of the nowcast system web page results figures into a 1 figure per module architecture in the refactor-nowcast-figures branch
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 <firstname.lastname@example.org> 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
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.