Squash Branch

Turn noisy Git history into a small, reviewable commit stack without changing the final code.

Workflow

1. Define the commit range.
2. Review each commit's purpose and files.
3. Group related commits.
4. Create a backup branch.
5. Rebuild the commits.
6. Compare the rebuilt tree with the backup.
7. Run the project's tests and build.
8. Push with --force-with-lease.

1. Define the range

Use the range named by the user:

• Feature branch: <base>..HEAD
• Since a commit or tag: <ref>..HEAD
• Today's work: commits since local midnight
• Recent work: the requested number of commits

Confirm the current branch, working tree, remote, and selected base before changing history.

If there are uncommitted changes, commit them only when the user asks. Otherwise, ask whether to commit or stash them.

2. Review the commits

Read the log, messages, and file statistics:

git log <range> --reverse --format="%H %s%n%b---"
git diff <base>...HEAD --stat
git show --stat <sha>

Group commits by purpose. Combine fixups, tests, documentation, and polish with the change they support. Keep unrelated features, infrastructure changes, and reverts separate.

Prefer a few clear commits, but do not force unrelated work into an arbitrary commit count.

3. Create a backup

git branch backup/<branch>-<date> HEAD

Record the original tip and base commit. The backup protects the exact tree while history is rebuilt.

4. Rebuild the history

Reset to the base only after the backup exists:

git reset --hard <base>

For contiguous groups, restore the tree at each group's tip:

git read-tree -u --reset <group-tip>
git commit -m "<clear subject>" -m "<why this group exists>"

For non-contiguous groups, apply the selected commits without committing, then create one new commit:

git cherry-pick -n <sha-1> <sha-2> <sha-3>
git commit -m "<clear subject>" -m "<why this group exists>"

Keep commits in their original order unless reordering is required to form a logical group. Stop and report conflicts rather than guessing how to resolve them.

Do not use git checkout <sha> -- . to restore a full tree. It can leave files that later commits deleted.

5. Verify

The rebuilt tree must exactly match the backup:

git diff --exit-code backup/<branch>-<date> HEAD
git log <base>..HEAD --oneline
git status --short

Run the repository's normal quality gates. Include tests and a production build when available.

If the tree differs or a quality gate fails, do not push.

6. Push safely

Rewriting main or master requires clear user approval. Warn that other checkouts may need to reset after the push.

git push --force-with-lease origin <branch>

Never use a plain --force push. Delete the backup only after verification and the push both succeed.

Commit messages

• Use an imperative subject of 72 characters or fewer.
• Explain why the group exists in one or two body sentences.
• Do not list every changed file.

Final report

Report:

• The old and new commit counts
• The new commit list
• Quality gates and their results
• The pushed branch
• Any reset command collaborators may need