Using Mercurial Phases and the Evolve Extension to Rewrite Local History Safely

The Problem: Accidentally Rewriting Shared History

When you work on a feature branch locally, you often realize a commit needs a small fix—perhaps a typo, a missing file, or a tweak to the commit message. If you simply run hg commit --amend on a changeset that has already been pushed to a shared repository, you risk rewriting public history. That can break clones for teammates and cause confusing merge Mercurial will reject the operation, but low‑level commands can bypass the safety net if you’re not careful.

Thesis: Phases Guard Public History; Evolve Lets You Rewrite Drafts Safely

Mercurial tracks each changeset with a phase—public, draft, or secret. New local commits start in draft. When you push or pull from a repository that others also use, Mercurial promotes those changesets to public. The phase system prevents commands like hg strip or hg rebase from touching public changesets unless you explicitly override it.

The evolve extension builds on this model. It provides high‑level commands (hg amend, hg fold, hg split, hg evolve) that work only on draft changesets. When you amend a parent changeset, hg evolve automatically rebases its descendants onto the updated parent, keeping the history linear and eliminating manual fix‑ups.

Worked Example: Amending a Draft Commit and Evolving Its Children

1. Set up a scratch repository (run where you have write permission):

   hg init example-repo
   cd example-repo
   echo 'initial' > file.txt
   hg add file.txt
   hg commit -m 'Initial commit'

2. Create a draft stack (three local commits, none pushed):

   echo 'change A' >> file.txt
   hg commit -m 'Add A'
   echo 'change B' >> file.txt
   hg commit -m 'Add B'
   echo 'change C' >> file.txt
   hg commit -m 'Add C'

3. Verify the phases (all should be draft):

   hg phase

   You’ll see output like:

   0: draft  Initial commit
   1: draft  Add A
   2: draft  Add B
   3: draft  Add C
   

4. Amend the middle commit (for instance, fix a typo in its message):

   hg amend -m 'Add A (fixed)' -r 1

   This creates a new changeset that obsoletes the old one; the old changeset becomes obsolete but remains in the repository until evolved.
5. Run evolve to rebase the child changesets:

   hg evolve

   After this, hg log --graph shows a linear chain where the amended commit is the parent of the former "Add B" and "Add C" commits, now rebased onto the updated parent.
6. Confirm the result:

   hg log --graph -T '{rev}:{phase} {desc|firstline}\n'

   You should see all three commits still marked draft (none have been pushed yet).

Trade‑offs and Limitations

• Cognitive load: You must remember to run hg evolve after any amendment, fold, or split. Forgetting it leaves obsolete changesets and can create "unstable heads" that confuse newcomers.
• Extension availability: evolve is not part of the core Mercurial distribution; you need to enable it in ~/.hgrc or the repository’s .hg/hgrc:

  [extensions]
  evolve = 

  Verify with hg help extensions before relying on it in automation.
• Collaborator responsibility: If you push rewritten draft changesets to a shared repo and others pull them, they must also run hg evolve (or hg pull --rebase with evolve enabled) to avoid seeing obsolete heads.
• Phase bypass risk: Low‑level commands like hg strip -r can still remove public changesets if you force them. Treat phases as a guard, not an absolute lock.

Actionable Closing

To safely rewrite local history in Mercurial:

1. Keep work-in‑progress commits in the draft phase—avoid pushing them until they are ready.
2. Enable the evolve extension once per environment.
3. When you need to adjust a draft changeset, use hg amend, hg fold, or hg split as appropriate.
4. Immediately run hg evolve to propagate the change to any descendant commits.
5. Before sharing, run hg phase --force -r public only when you are certain the changeset should become immutable.

By combining Mercurial’s built‑in phase protection with the evolve extension’s automatic rebasing, you can iterate locally with confidence, knowing that shared history stays intact and your teammates won’t be surprised by unexpected heads.