Architecting Lineage with Mercurial Named Branches

The Problem: Permanent Lineage vs. Volatile Pointers

In many version control systems, a branch is a movable pointer to a specific commit. While efficient for short-lived features, this approach loses the historical context of which branch a specific change originally belonged to once the pointer is deleted. When auditing long-term releases or regulatory changes, you need a record that persists regardless of whether the branch is currently "active."

Mercurial solves this by implementing Named Branches as permanent metadata embedded directly within the changeset. The takeaway is that a named branch is not a pointer, but a property of the commit itself. This ensures that the lineage is immutable and travels with the data across clones and pushes.

Requirements for Lineage Tracking

To maintain a verifiable history of feature development or release cycles, the system must meet these criteria:

• Persistence: The branch identity must survive the deletion of local workspace references.
• Global Visibility: Every collaborator must see the same branch name for a specific commit.
• Auditability: The history must show exactly where a branch diverged and where it was merged back into the main line.

The Design: Embedded Metadata

The smallest suitable design for this requirement is to store the branch name in the changelog of the repository store. Instead of a separate file mapping names to hashes, the branch name is a field in the commit record.

Because the branch name is part of the commit, it cannot be changed without altering the commit's hash (which would change the identity of the commit). This creates a rigid but reliable boundary: once a commit is made to "Release-1.0," that commit is forever associated with "Release-1.0."

Data Boundaries and Trust

Data boundaries in Mercurial are managed at the store level. When you perform an hg update, the system queries the index to find the most recent changeset associated with the requested branch name. Trust is maintained through the hash chain; since the branch name is part of the hashed data, a malicious actor cannot rename a branch in a pushed changeset without breaking the repository's integrity checks.

Operational Implementation

To implement a named branch, you must set the branch identity before committing. This operation changes the state of the working directory's metadata.

# Run from the root of your Mercurial repository
# Permission: Standard user with write access to the repository
hg branch feature-audit-log
hg commit -m "Implementing audit logging"

Verification and Diagnostic Checks

Because named branches allow for multiple "heads" (divergent paths within the same branch name), you must verify the state of the lineage to avoid accidental divergence.

• Check for Divergence: Run hg heads. If you see multiple entries for the same branch name, the lineage has split and requires a merge.
• Verify Persistence: Clone the repository to a new directory and run hg branches. The named branch will appear even if no one is currently "on" that branch.

Comparison: Named Branches vs. Bookmarks

Failure Modes and Constraints

The primary failure mode of this architecture is Branch Pollution. Because named branches are permanent, they cannot be deleted using standard commands. Over time, a repository can accumulate hundreds of stale branch names that clutter the output of hg branches.

Constraints:

• Immutability: You cannot "rename" a branch for existing commits.
• Cleanup: Removing a named branch from history requires the strip or evolve extensions, which rewrite history and can cause synchronization conflicts for other collaborators.

Conditions for Design Change

This architecture is ideal for stability and auditing. However, you should shift to Bookmarks if your workflow requires:

• Frequent creation and deletion of temporary feature branches.
• The ability to move a branch pointer to a previous commit (rewinding).
• A clean hg branches list that only shows currently active work.

Rollback: To revert a branch name change before a commit is made, use hg update to return to a previous revision, which resets the current branch context to that of the target revision.