Mercurial Histedit: Interactive History Rewriting for Clean Commits

The Problem: Messy History Before Merge

When developing a feature branch, you often end up with several small, incremental commits that don't read well as a cohesive unit. Mercurial's histedit extension lets you reorder, drop, squash, or edit commits interactively before sharing them with others.

Enabling Histedit

First, enable the extension in your repository's configuration file (.hg/hgrc or .hgrc):

[extensions]
histedit =

Run hg help histedit to confirm it's available.

Running Histedit

Execute hg histedit <changeset> from the command line, replacing <changeset> with the revision number or hash of the commit you want to start editing from. For example:

hg histedit 3

This opens an interactive terminal showing a revision graph with commit messages and available commands:

Command	Mean
d	drop (delete) this commit
m	squash with previous commit
e	edit commit message or changes
j	join with next commit
r	rebase onto specified commit
p	pick (keep) this commit

Worked Example: Consolidating a Feature Branch

Imagine you have three commits on a feature branch:

changeset:   5:f3a2b1c
user:        alice
date:        Mon Nov 10 14:30:00 2025 +0000
summary:     Add login form widget

changeset:   4:e8d7c6f
user:        alice
date:        Mon Nov 10 15:45:00 2025 +0000
summary:     Fix validation bug in login form

changeset:   3:d2c1b0a
user:        alice
date:        Mon Nov 10 16:20:00 2025 +0000
summary:     Update styling for login page

You want to squash these into a single clean commit. Run:

hg histedit 3

In the histedit interface, mark commits 3 and 4 with m and commit 5 with d (or use m for all three and let the final commit be the consolidated result). Save and exit. Histedit will then launch your editor to let you craft a new commit message.

Important Limitations

• Clean working directory required: Histedit cannot run with uncommitted changes. Either commit them first or use hg shelve to temporarily store them.
• Cannot edit the most recent commit: By default, histedit won't let you edit the current working directory state. Use hg histedit --edit or make a dummy commit first.
• Rewrites public history: If commits have already been pushed and shared, histedit will rewrite them, creating new hashes. This can disrupt collaborators who have based work on the old history.
• Manual merge conflict resolution: Complex merges or large binary files may trigger conflicts during the rewrite process that require manual intervention.

Verifying the Result

After histedit completes, verify the changes with:

hg log -r '::.' --template '{rev}:{node|short} {desc}
'

Check that the new commit history reflects your intended changes. If something went wrong, use hg reflog to find the old revisions and recover.

Common Mistakes to Avoid

1. Running on shared history: Never histedit commits that others have pulled. Coordinate with your team first.
2. Editing without a clean state: Always ensure your working directory is clean before starting.
3. Forgetting to update the commit message: After squashing, histedit opens your editor. Write a clear, descriptive message that captures the essence of the combined changes.