| name | rewrite-history |
| description | Rewrite branch into clean, narrative-quality commits. Creates backup, reimplements on fresh branch, verifies byte-identical, then replaces original branch history. |
Rewrite the current branch's history into clean, narrative-quality commits suitable for code review.
Goal
Transform messy development history into a logical story reviewers can follow commit-by-commit. Original branch is rewritten; backup preserved for rollback.
Arguments
$ARGUMENTS = optional flags (--auto skips interactive approval)
Preconditions
Abort with clear error if:
- On main/master branch
- Uncommitted changes exist
- No commits to rewrite (branch matches main)
Execution
- Create backup branch:
{branch}-backup-{timestamp} — permanent until manually deleted
- Analyze the diff between current branch and main—understand the complete change set
- Create temp branch from main for clean reimplementation
- Plan the narrative—structure changes into logical, self-contained commits (foundations → features → polish)
- Reimplement by recreating changes commit-by-commit with conventional commit messages; use
--no-verify for intermediate commits
- Verify byte-identical:
git diff {original-branch} MUST be empty—abort if any difference
- Replace original branch: point original branch to clean history (final commit runs hooks normally)
- Offer to push with
--force-with-lease
Verification Requirement
The byte-identical check is non-negotiable. If shows ANY difference after reimplementation:
