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-repo
include:
- Development of v2.0 of the
SalishSeaCmdProcessor
to support NEMO-3.6 in theSalishSeaCmd-3.6
branch - Separation of the nowcast system code from the
SalishSeaToolsPackage
into theSalishSeaNowcastPackage
in theSalishSeaNowcast
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 <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.