Rewrite Commit History

Rewrite Commit History

Rewrite a feature branch's messy commit history into clean, conventional commits that tell a progressive, linear story — safe to read, review, and bisect.

Workflow

Step 1 — Guard

Abort if the working tree is dirty. A clean rewrite requires a clean state.

git status --porcelain

If output is non-empty: stop. Tell the user to stash or commit pending changes first.

Then detect the parent branch. The entire rewrite depends on using the correct base — a wrong base means wrong diffs and wrong commits.

git log --oneline --decorate --graph --all | head -20

Check if the branch has commits relative to main:

git log --oneline main..HEAD 2>/dev/null | wc -l

If the count is 0 or the command fails, the branch was likely forked from something other than main. Ask the user to confirm the target branch before proceeding. Do not assume main.

Common alternatives: master, develop, staging, origin/main.

Once confirmed, set the base branch for all subsequent steps:

BASE=<confirmed-branch>  # e.g. BASE=main or BASE=develop

Step 2 — Backup

Create a timestamped backup branch at the current HEAD before touching anything.

BRANCH=$(git rev-parse --abbrev-ref HEAD)
EPOCH=$(date +%s)
git branch backup/${BRANCH}-${EPOCH}

Confirm backup was created. This is the restore point if anything goes wrong.

Step 3 — Analyze

Read the full diff and log between the base branch and HEAD.

git log --oneline ${BASE}..HEAD
git diff --stat ${BASE}...HEAD

For large branches (many files), start with --stat to see the scope before reading the full diff. Then read individual files as needed to understand the changes in depth.

git diff ${BASE}...HEAD

Identify the logical units of work. Look for:

• Feature additions (new files, new functions)
• Bug fixes (targeted changes to existing code)
• Refactors (structural changes with no behavioral difference)
• Config/tooling changes
• Tests added or updated
• Docs updated

Group related changes together. A good commit is one logical unit, not one file.

Step 4 — Plan

Present the proposed commit sequence to the user. Each entry must include:

• The conventional commit message (type + scope + subject)
• A brief summary of which files/changes are included

Order commits so each builds on the previous — the branch should compile and make sense at every point.

Example plan format:

1. feat(auth): add JWT token generation
   Files: src/auth/token.ts, src/auth/types.ts

2. feat(auth): add login endpoint with token issuance
   Files: src/routes/auth.ts, src/routes/auth.test.ts

3. chore: update env example with JWT secret
   Files: .env.example

Before confirming, verify every file that appears in git diff --stat ${BASE}...HEAD is assigned to at least one commit in the plan. Unassigned files will cause the tree parity check to fail in Step 6.

Step 5 — Confirm

Wait for user approval before executing. Accept:

• Approval as-is
• Edits to commit messages
• Reordering of commits
• Splitting one commit into two
• Merging two commits into one

Do not proceed until the user confirms the plan.

Step 6 — Execute

Soft-reset to the merge base, then create each commit one at a time with selective staging.

git reset --soft $(git merge-base ${BASE} HEAD)

For each planned commit:

git add <specific files for this commit>
git commit -m "<conventional commit message>"

Use selective git add — never git add -A for a batch. Each commit must contain only its planned files.

After all commits, verify tree parity against the backup:

BRANCH=$(git rev-parse --abbrev-ref HEAD)
# Find the backup branch (most recent for this branch).
# sort works correctly here because the epoch timestamp is always 10 digits (valid until 2286).
BACKUP=$(git branch --list "backup/${BRANCH}-*" | sort | tail -1 | tr -d ' ')
git diff HEAD ${BACKUP}

If diff is non-empty: something was lost or corrupted. Restore immediately:

git reset --hard ${BACKUP}

Report the failure and stop.

Step 7 — Verify

Confirm success:

• git log --oneline ${BASE}..HEAD shows the new clean history
• git diff HEAD ${BACKUP} is empty (tree parity confirmed)
• Report the backup branch name so the user can delete it when satisfied

Conventional Commit Types

Format: type(scope): subject — subject is imperative, lowercase, no period.

Breaking changes: Append ! after type/scope, e.g. feat(api)!: rename endpoint.

Base Branch Override

Default base is main. Override with BASE=<branch> before running, or ask the user if uncertain.

Common alternatives: master, develop, staging, origin/main.

Examples

Positive Trigger

User: "Can you clean up my commits before I open this PR? It's a bunch of WIP saves."

Expected behavior: Use this skill. Start with Step 1 (guard check), then proceed through all steps.

Positive Trigger

User: "Rewrite my commit history into conventional commits."

Expected behavior: Use this skill. Follow the full 7-step workflow.

Non-Trigger

User: "Write a commit message for my current changes."

Expected behavior: Do not use this skill. Write a single commit message directly.

Non-Trigger

User: "Squash my last 3 commits into one."

Expected behavior: Do not use this skill. Use git reset --soft HEAD~3 directly and commit.

Troubleshooting

Working Tree Is Not Clean

• Error: git status --porcelain returns output before the rewrite starts.
• Cause: Unstaged or staged changes exist in the working directory.
• Solution: Ask the user to stash (git stash) or commit pending changes, then retry.

Merge Base Cannot Be Found

• Error: git merge-base ${BASE} HEAD fails or returns unexpected output.
• Cause: The base branch name is wrong, or the branch has no common ancestor with the specified base.
• Solution: Ask the user to confirm the base branch. Try git log --oneline to see branch history.

Tree Parity Check Fails After Rewrite

• Error: git diff HEAD ${BACKUP} is non-empty after all commits are created.
• Cause: One or more files were missed during selective staging, or a file was double-staged.
• Solution: Immediately restore with git reset --hard ${BACKUP}. Report which files diverged. Re-plan and retry.

Backup Branch Not Found During Verify

• Error: git branch --list "backup/${BRANCH}-*" returns empty.
• Cause: Branch was deleted or the shell variable substitution failed.
• Solution: Run git branch --list "backup/*" to locate any backup branches. Do not proceed with verification until the backup is confirmed.