Managing Long-Term Feature Tracking with Mercurial Named Branches

The Problem with Ephemeral Branches

In many version control systems a branch is a lightweight pointer to a commit. When the pointer is removed after merge the structural record of the feature's isolation often vanishes, leaving only a merge commit. For large engineering projects this makes auditing the lifecycle of a specific feature difficult once the branch is gone.

Mercurial treats Named Branches as permanent metadata embedded in every commit. The takeaway is simple: if you need a permanent searchable record of which commits belonged to a specific feature even years after merge, named branches are the correct tool.

How Named Branches Differ from Pointers

In Mercurial creating a named branch changes a property of the commit object itself. Every commit made on that branch carries the branch name in its header.

• Persistence: The branch name stays with the commit forever. It is not deleted when the branch is merged.
• Visibility: You can list all active named branches using hg branches, but the history of closed branches remains accessible via the log.
• Identity: Because the branch is a property of the commit you can filter the entire project history to see every change associated with a specific feature ID.

Implementing a Feature Workflow

To use named branches you must explicitly set the branch name before committing. This ensures the metadata is baked into the resulting changeset.

Worked Example: Feature Isolation

Assume you are working in a repository initialized with hg init. You need to develop a new authentication module without polluting the default branch.

1. Create the branch. Run in the repository root with write permission. This tells Mercurial that all subsequent commits should be tagged as auth-module.

   hg branch auth-module

2. Commit changes. Make code changes and commit them.

   hg commit -m 'Implement OAuth2 flow'

3. Verify the metadata. Check the log to see the branch assignment.

   hg log -G

4. Merge back to default. Switch back to the main line and pull the changes in.

   hg update default
   hg merge auth-module

Verification Check

After the merge run hg log. Commits originally made on auth-module still display that branch name even though the working directory is back on default. This provides a clear audit trail of the feature's origin.

The Trade-off: Repository Clutter

The primary limitation of named branches is permanence. Because they are embedded in commit history you cannot simply delete a named branch to clean up your list. If a team creates a new named branch for every tiny bug fix the output of hg branches will become an unmanageable list of legacy names.

To mitigate this use Bookmarks for short-lived ephemeral tasks and reserve Named Branches for significant architectural features or release tracks that require long-term traceability.

Practical Summary

Use named branches when the context of the work is as important as the code itself. Establish a naming convention such as feat-JIRA-123 and use bookmarks for temporary experiments. Removing a branch entirely from history requires the strip or evolve extensions because it modifies immutable history and carries repository rewrite risk.