When and how should you rewrite Git history?

Question

Accepted Answer

Git lets you **rewrite history** — amending, rebasing, squashing, or removing commits — to clean up commits or fix problems. It's powerful but must be done carefully: rewriting **shared** history causes serious problems, so the rules around it are critical. ## Ways to rewrite history ```text git commit --amend → modify the most recent commit (message or content) git rebase -i → squash, reword, reorder, edit, drop commits (interactive) git rebase → replay commits onto another base (linear history) git reset → move the branch pointer (discard/uncommit) git filter-repo → rewrite MANY commits (remove a file/secret from all history) → All of these change commit HASHES (rewriting = creating new, different commits). ``` ## The golden rule ```text ⚠️ NEVER rewrite history that has been PUSHED/SHARED (that others may have): → rewriting changes commit hashes → your history DIVERGES from collaborators' → they'll have the old commits; pulls create duplicates/conflicts; chaos ensues → forces everyone to painfully reconcile → a serious disruption ✓ Rewrite ONLY local, unpushed commits (cleanup before sharing). ✗ On shared branches → use REVERT (a new undoing commit) instead, which is safe. ``` ## Legitimate uses of rewriting (local) ```text ✓ Clean up messy WIP commits before opening a PR (squash, reword) → clean history ✓ Fix a mistake in the last commit (amend) before pushing ✓ Keep a feature branch linear/up-to-date with main (rebase) before sharing ✓ Remove a SECRET accidentally committed (filter-repo) — though if it was PUSHED, the secret must be ROTATED (it's already exposed; rewriting alone isn't enough) ``` ## If you must rewrite shared history (rare) ```text → COORDINATE with the whole team (everyone stops, re-syncs) → Force-push carefully: git push --force-with-lease (safer than --force — checks first) → Everyone must reset/re-clone to the rewritten history → Do this only when truly necessary (e.g. purging a leaked secret) and with agreement. ``` ## Why it matters Understanding when and how to rewrite Git history is important senior-level knowledge because history rewriting is **powerful but dangerous**, and understanding the rules — especially around shared history — prevents serious problems while enabling legitimate cleanup. Knowing the **ways to rewrite** (amend for the last commit, interactive rebase for squashing/rewording/reordering, rebase for linear history, reset, filter-repo for large-scale changes) and that they all **change commit hashes** (creating new commits) is the foundation. Most critically, understanding the **golden rule — never rewrite shared/pushed history** — is essential because rewriting changes hashes, causing your history to diverge from collaborators' (who still have the old commits), leading to duplicates, conflicts, and painful reconciliation; rewriting shared history is a serious disruption that this rule prevents, with **revert** (a safe new undoing commit) being the correct approach for shared branches instead. Understanding the **legitimate local uses** (cleaning up WIP commits before a PR, amending mistakes before pushing, rebasing to stay linear before sharing — all on local, unpushed commits) clarifies when rewriting is appropriate and valuable. A crucial security nuance: if a **secret was committed and pushed**, rewriting history to remove it is insufficient — the secret is already exposed and must be **rotated** (an important real-world security point). Knowing how to **handle the rare necessary rewrite of shared history** (team coordination, `--force-with-lease` rather than `--force`, everyone re-syncing) reflects mature judgment. Since history rewriting is powerful but causes serious problems when misused on shared history, and since understanding the golden rule, legitimate uses, and safe practices is essential for using it responsibly, understanding when and how to rewrite Git history is important senior-level knowledge — a topic where understanding the safety rules (especially never rewriting shared history) prevents real collaboration disasters, reflecting the judgment expected for senior roles working with Git in teams.