Managing Long-Term Feature Audit Trails with Mercurial Named Branches

The Problem: Losing the 'Why' in Merge History

In many VCS, branches are lightweight pointers. After a merge and pointer deletion, the context of commits blends into main trunk. Later, you can see what changed but not which feature they came from.

Mercurial treats branches as permanent metadata. A Named Branch is a property on each commit, preserving identity after merges.

Named Branches vs Bookmarks

Bookmarks behave like Git branches—pointers that can move. Named branches are baked into the changeset, so every commit carries the branch name.

Worked Example

# Create feature branch
hg commit -b feature-login -m 'Add login form'
# Verify
hg branches
# Switch to default
hg update default
# Merge
hg merge feature-login
hg commit -m 'Merge feature-login'
# Check history
hg log -B

Closing Branches

To keep hg branches tidy, mark a branch as closed after merging:

hg commit --close-branch -m 'Closing feature-login'

Trade-offs

Permanence means you cannot rename or delete a branch from history without risky extensions. Overuse for tiny changes clutters the branch list.

Use bookmarks for short experiments; use named branches for features needing audit trails.

Verification

Run hg log -B to see branch labels on commits. A healthy project shows varied labels that eventually become closed.