Using Mercurial Named Branches: Best Practices and Common Pitfalls

What Are Named Branches?

In Mercurial a named branch is a permanent, repository‑wide label that is recorded in the metadata of every changeset it touches. Unlike Git’s lightweight branches, the name is stored inside the changeset itself, so it travels with the commit when you push or pull.

Creating and Using a Named Branch

Switch to a clean working directory, then set the branch name for the next commit:

# run in the repository root
hg branch feature‑awesome
# verify the current branch
hg branch

Now any hg commit you make will be tagged with feature‑awesome. To see all branches that have ever been used, run:

hg branches

This lists every branch that has at least one commit, along with the tip revision of each.

Push/Pull Behavior and Branch Visibility

When you push, Mercurial only transfers changesets that are reachable from the destination’s branches. If the target repository does not already contain feature‑awesome, the push will fail unless you adjust the configuration:

# allow pushing new branches
# in the source repo’s .hg/hgrc
[push]
    default = http://example.com/repo
    allow-new-branch = true

Alternatively, use hg push --new-branch to override the default behaviour for a single push. Pulling behaves similarly: the remote branch must exist, or the pull will be rejected.

When to Avoid Named Branches

• Short‑lived features: Named branches cannot be deleted or renamed; once a branch name is used it stays forever in the history.
• Feature flags or experiments: Use hg bookmark or hg phase instead; these are lightweight and can be discarded without leaving a permanent tag.
• Collaborative workspaces: Unnamed branches reduce the risk of accidentally propagating temporary work to others.

Common Mistakes and How to Fix Them

1. Assuming a branch name is only a label

   Because the name is stored in each changeset, new commits on the same branch will always carry the name. If you later merge the branch into default, the merged changesets retain the original branch name, which can clutter the log.

2. Trying to delete a named branch

   There is no hg branch --delete. To remove a branch, you must strip all changesets that belong to it (which rewrites history) or simply ignore it. Use hg strip --branch feature‑awesome with caution.

3. Misreading hg branches as a graph

   The command only lists branch names that have commits. It does not show merge relationships. Use hg log -G for a visual graph.

Checking Your Branch History

Verify that the branch name is embedded in changesets:

# show branch name for the latest commit
hg log -r . --template "{branch}\n"
# inspect the raw changeset file (requires hg debugdata)
hg debugdata --changeset 1234

If the output shows feature‑awesome, the branch annotation is present. Remember that this annotation is immutable; you cannot change it without rewriting history.

Limitations and Practical Tips

• Named branches are global; they apply to the entire repository, not to a subset of files.
• They are immutable; once a commit records a branch name, you cannot change it without a history rewrite.
• When collaborating, be explicit about which branches you intend to share. Use hg push --new-branch only when you truly need to create a new branch on the remote.
• For feature‑level isolation, consider bookmarks: hg bookmark feature‑awesome. Bookmarks can be moved, renamed, or deleted without touching the commit history.

By understanding these constraints, you can make an informed decision about whether a named branch is the right tool for your workflow.