Tidy Commits

Tidy an existing branch into a clear, reviewable commit story while preserving the intended final tree.

Quick start

For local branch history cleanup only — for ordinary new commits use the repo's normal commit workflow.

Inspect state → refuse unclear or unrelated working-tree changes → record the pre-rewrite tip → plan base..HEAD (keep / squash / fixup / reword / reorder / split / drop) → show the plan and exact commands → rebase non-interactively → verify the final tree and tests before any push.

Preflight

• Determine the base with repo evidence: PR base, origin/HEAD, or the user-provided base.
• Fetch first: git fetch --prune --all.
• Require a clean, understood state. If git status shows a rebase, merge, cherry-pick, or mixed unrelated changes, stop and ask.
• Record current state with git log --oneline --decorate --stat <base>..HEAD, git diff --stat <base>...HEAD, and nearby branch context.
• Record the pre-rewrite tip: git rev-parse HEAD (call it <pre>). Do not create a backup branch or tag: the reflog already keeps every tip the rewrite replaces (git reflog <branch>; after one rewrite the old tip is <branch>@{1}), and extra refs only pile up for someone to clean. The reflog covers committed history only, which the clean-state rule above guarantees; it is local to this clone and expires (unreachable entries after 30 days by default), so it is the recovery path for this session, not an archive.

Cleanup plan

Classify each commit before rewriting.

Do not blend unrelated concerns just to reduce commit count. A good stack is a readable story, not necessarily one commit.

• Mixed-concern fixups guard: Never fixup or squash a WIP or fixup commit into a target commit if the WIP commit contains changes to files in unrelated modules. Split the WIP commit first (or perform a soft reset and stage hunk-by-hunk) so each change is merged into its corresponding feature commit.
• Outdated Base & Soft-Reset Guard: Never run git reset --soft <base> if the feature branch was branched off an older base commit and <base> has moved ahead. Soft-resetting across a diverged base will stage accidental deletions of new files added in <base>. Always rebase onto <base> first (git rebase <base>) or checkout feature files onto a fresh <base>.

Rewrite

Collapsing the whole range into one commit? Skip the todo: git rebase or git reset --soft <base> && git commit (ensuring the branch is rebased onto <base> first so no files from <base> are accidentally deleted). This leaves the final tree staged and re-commits it as a single commit — nothing is replayed, so there are no conflicts (it signs automatically when commit.gpgsign is set). Use the rebase todo below only when you need selective fixup, reorder, or split.

Otherwise prefer non-interactive rebase patterns (no editor prompts; set GIT_EDITOR=true to prevent launching GUI editors like Zed). Generate the todo oldest-first (the reverse of git log), edit the actions and order, then feed it back:

git log --reverse --format='pick %h %s' <base>..HEAD > "${TMPDIR:-/tmp}/tidy-commits-todo"
# edit that file, then:
GIT_EDITOR=true GIT_SEQUENCE_EDITOR="cp ${TMPDIR:-/tmp}/tidy-commits-todo" git rebase -i --update-refs <base>

The first column is the action; lines run top (oldest) to bottom (newest):

pick   a1b2c3d Add parser
fixup  f4e5d6a fix typo in parser   # folds into the pick above, discards its message
pick   7890abc Add CLI flag
edit   def1234 Wire CLI to parser   # stop to amend, then git rebase --continue

Avoid reword in todo files because it opens an editor; use edit, then git commit --amend -m ... and git rebase --continue.

Recovery: mid-rebase, git rebase --abort restores the pre-rebase state; after a bad finish, git reset --hard <pre> (or the matching git reflog <branch> entry). A stacked branch moved by --update-refs has its own reflog entry for its old tip.

When a branch contains merge commits, ask whether to preserve them with --rebase-merges or flatten them. Do not guess.

Stacked Branches

Before rewriting, detect local branches that point inside the rewritten range. Use --update-refs by default so stacked branches follow rewritten commits instead of being orphaned.

Flag branches checked out in another worktree: Git will not move those refs. Report them for manual verification before pushing.

If the repo uses a stacked-PR tool such as gh stack, prefer that tool's sync/rebase workflow over hand-editing branch relationships.

Verification

After rewriting:

• Compare the final tree against <pre> unless commits were intentionally dropped: git diff --stat <pre> HEAD and git diff <pre> HEAD.
• Inspect per-commit file scope & file absence: Run git diff --name-status <base>..HEAD and verify that no unrelated files (or files not touched by the original feature branch) were accidentally deleted or added.
• Show the new story: git log --oneline --decorate <base>..HEAD.
• Run relevant tests, type checks, linters, or focused reproductions — only where the tree comparison showed a difference, or commits were intentionally dropped. Run them in the primary session rather than a subagent, since a failure needs their full output. A rewrite that preserved the tree cannot change what they report.
• If branch protection requires verified signatures, check commit signatures with git log --show-signature <base>..HEAD or the repo's GitHub status. Re-sign rewritten commits before pushing when needed.

Push Safety

Never use plain git push --force.

If the branch was already pushed, list every ref that changed and show exact commands first.

git push --force-with-lease origin HEAD:<branch>
git push --force-with-lease origin <moved-stacked-branch>

Ask for confirmation before force-with-lease pushes.

Stop Conditions

Stop and ask when:

• The intended base branch is ambiguous.
• A commit's purpose cannot be inferred from code, tests, or messages.
• Conflict resolution requires product judgment.
• Dropping a commit may change behavior.
• Another worktree or remote branch would be affected and cannot be verified.