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 git diff {backup-branch} shows ANY difference after reimplementation:
-
Abort immediately
-
Report exactly what differs
-
Leave backup branch intact for recovery
Constraints
-
Analyze the complete diff only—ignore original commit history
-
One concern per commit—atomic, independently revertible
-
Conventional commit messages: type(scope): description
-
Never add "Co-Authored-By" or "Generated with Claude Code"
-
Always use --force-with-lease for push (never --force )
Interactive Mode
Unless $ARGUMENTS contains --auto :
-
Present proposed commit plan before execution
-
Allow adjustment or cancellation
Rollback
If anything goes wrong: git reset --hard {branch}-backup-{timestamp}
Output
Report commit count, backup branch name, and the new commit log.