Resolving Multiple Heads in Mercurial: A Diagnostic Guide

The Problem: Push Failures Due to Multiple Heads

When attempting to push changes to a central Mercurial repository, you may encounter an error stating that the push would create multiple heads on the destination. This happens because Mercurial allows multiple "heads" (the most recent commit in a line of development) to exist on a single branch. While this is a feature for local development, most central servers are configured to require a single head to maintain a linear history.

Diagnostic: Identifying Divergence

The first step is to confirm that your local repository has diverged from the remote. Use the following table to identify the state of your branch.

Command	Observation	Meaning
hg heads	Two or more revisions listed for one branch	Divergent history; multiple developers committed independently.
hg log -G	A graph showing a "fork" in the commit line	Visual confirmation of where the paths split.
hg incoming	Changes available on remote not yet in local	Local head is behind or divergent from the server.

Step-by-Step Resolution Path

Follow these checks in order to determine the safest way to unify your branch.

1. Check for Ancestry

Determine if one head is simply ahead of the other without any conflicting changes. If you pull changes and find that your local work is a direct descendant of the remote head, a simple merge is straightforward.

2. Analyze File Overlap

Run hg merge [revision]. Mercurial will attempt to integrate the changes. If the output indicates "no conflicts," the changes occurred in different files or different lines of the same file.

3. Evaluate Commit Validity

Decide if the divergent head contains intentional work. If a head was created by an accidental commit to the wrong branch or a failed experiment, it may be better to remove it entirely rather than merging it into the main line.

Applying the Fix

Fix A: Merging Divergent Heads (The Standard Path)

Use this method when both heads contain valuable work that must be preserved.

1. Run the merge: From your working directory, run hg merge [revision_id]. Replace [revision_id] with the hash of the other head identified via hg heads.
2. Resolve Conflicts: If Mercurial flags conflicts, open the affected files. Look for conflict markers (<<<, ===, >>>), manually edit the file to the desired state, and save.
3. Commit the Merge: Run hg commit -m "Merge divergent head [revision_id]". This creates a new commit with two parents, unifying the history.

Fix B: Stripping Unwanted Heads (The Destructive Path)

Use this method only if one head was created in error and contains no data you wish to keep. Warning: This permanently removes revisions from the repository store.

1. Identify the bad revision: Use hg log -G to find the hash of the commit that started the divergence.
2. Strip the revision: Run hg strip [revision_id]. This requires the strip extension to be enabled in your .hgrc file.

Verification and Risks

To verify the resolution, run hg heads. The output should now show only one revision for your current branch. Once verified, execute hg push to update the central server.

Critical Risks:

• Amending Shared History: Never use hg commit --amend on a revision that has already been pushed to a shared server. This rewrites the commit hash and will create new divergent heads for every other developer on the team.
• Data Loss: hg strip is irreversible. Always ensure you have a backup or a clone of the repository before stripping commits.

Escalation Criteria

If the following conditions occur, escalate to a repository administrator:

• The merge results in massive logical conflicts (code compiles but functionality is broken) that require architectural decisions.
• The hg strip command fails due to the revision being a parent of other critical commits.
• The central server rejects the push even after hg heads shows a single head (indicating a server-side hook or permission issue).