What it is: History rewriting is the process of altering a Git repository’s existing commit history — not by adding new commits on top, but by actually recreating some or all of the existing commits with different content, and replacing the originals entirely. git filter-repo is a dedicated, modern tool specifically built to perform this kind of large-scale history rewriting quickly, safely, and flexibly.

Why it exists: As covered in a related guide, git revert is Git’s safe, standard way to undo a change without touching history — but reverting only cancels a change’s effect going forward, while the original content remains fully present and recoverable in earlier commits. Sometimes that’s not good enough: if a password, a private file, or an enormous, unwanted binary was accidentally committed, the content itself needs to be genuinely removed from every commit that ever contained it, not just undone in a later one. git filter-repo exists specifically to perform that deeper, more thorough kind of surgery.

Where it’s used: History rewriting with git filter-repo is used for cleaning accidentally committed secrets out of a repository’s entire history, permanently removing large files that were mistakenly committed and are bloating the repository, splitting a large monorepo into smaller, focused repositories while preserving relevant history, and other large-scale, deliberate restructuring of a project’s commit history.

Practical example: A developer discovers that a database password was accidentally committed to a repository three months and two hundred commits ago. Simply deleting the password in today’s commit leaves it fully recoverable from that commit three months back. Using git filter-repo, the team can rewrite the entire history, removing that specific piece of content from every single commit that ever contained it, producing a cleaned history where the password never appears at all.

You may likeWhat Is Sparse Checkout?→

For many years, the standard way to rewrite Git history at scale was a built-in Git command with a notoriously difficult, error-prone interface, and painfully slow performance on large repositories — a tool the Git project’s own documentation eventually began actively warning people away from, for anything beyond the simplest cases. Rewriting history is inherently a delicate, high-stakes operation, and a difficult, slow, easy-to-misuse tool made that danger considerably worse: a small mistake in a complex, hard-to-verify command could silently corrupt a repository’s history in ways that were hard to detect until real damage had already been done.

git filter-repo was developed as a modern, actively maintained replacement, explicitly designed around three goals: genuine speed even on very large repositories, a much safer, harder-to-misuse interface with sensible defaults and built-in safety checks, and significantly more flexible, precise control over exactly what gets rewritten. It’s now the tool officially recommended by the Git project itself for history-rewriting tasks that go beyond the simplest, single-commit edits.

The core problem git filter-repo solves: how do you reliably, efficiently, and safely remove or transform specific content across a potentially enormous number of historical commits, without an error-prone process risking further damage to an already-sensitive operation?

This structure — analyze everything first, apply precise rules, then reconstruct — is a deliberate design choice: by understanding the repository’s full structure before making any changes, the tool can apply filtering rules consistently and correctly across the entire history in one coordinated pass, rather than making ad hoc, potentially inconsistent edits commit by commit.

flowchart LR
    A["Filtering rules are defined (what to remove or change)"] --> B["Tool analyzes the full existing history"]
    B --> C["It walks through commits in chronological order"]
    C --> D["Each affected commit's content is rebuilt per the rules"]
    D --> E["A new hash is computed for each rebuilt commit"]
    E --> F["Every later commit is also rebuilt, since parent hashes changed"]
    F --> G["Original history is replaced with the newly rewritten history"]
    

Step by step, in plain language: first, the person running the rewrite defines precisely what should change — perhaps “remove this specific file from every commit that ever contained it,” or “replace this specific piece of text wherever it appears.” Second, the tool reads through the repository’s entire relevant history to build a complete picture of every commit, tree, and blob involved. Third, it walks through history in chronological order, from the earliest affected commit forward. Fourth, for each commit that needs to change, it reconstructs that commit’s tree and content according to the filtering rules, producing new blob and tree objects as needed. Fifth, because a commit’s hash is derived from its content, including its parent’s hash, this reconstructed commit inevitably gets a brand-new hash — and every commit after it, even ones whose own content never changed, must also be rebuilt, since their parent reference now needs to point at the new hash of the commit before them. Finally, once the entire chain has been reconstructed, the repository’s branches are updated to point at this new, rewritten history, effectively replacing the original.

Notice that step 6 involves far more than a technical command — it requires genuine coordination with everyone else who might have a copy of the old history, a topic covered fully in Chapter 10.

Each of these operations follows the same fundamental internal process covered in Chapter 4 — analyze, apply rules, reconstruct, cascade forward — but targets a different, specific aspect of the history’s content or structure.

Running git filter-repo successfully rewrites the history in your local, working copy of the repository — but the original, unrewritten objects don’t just vanish from every place they’ve ever existed. As covered in a related guide on content hashing, Git’s object model is content-addressable, and the original objects containing the sensitive content may still be reachable from any other copy of the repository — a teammate’s local clone, a fork on GitHub, a backup, or any previously pulled copy — until each of those copies is also updated or discarded.

This is why history rewriting for security purposes is best understood as damage limitation and cleanup, not a guarantee that exposed content has been made unrecoverable everywhere it might have already spread — the credential rotation covered in Chapter 5 is the genuinely reliable safeguard, with history rewriting as an important, but secondary, cleanup step.

When a rewritten history is force-pushed to a repository hosted on GitHub, GitHub updates the relevant branch to point at the new history’s commits, and the old commits are no longer part of that branch’s visible history going forward. However, GitHub retains its own internal processes around garbage collection and caching, meaning old, now-unreferenced objects may not be immediately and completely purged from GitHub’s own storage the instant a force-push occurs — reinforcing the point made in Chapter 8 that timing and thoroughness matter, and that credential rotation remains the truly reliable safeguard.

It’s also worth knowing that pull requests, issue references, and other GitHub-specific metadata that referenced the old, now-replaced commit hashes can behave unpredictably after a history rewrite — GitHub does its best to track renamed and rewritten content where possible, but a large-scale history rewrite is a fundamentally disruptive event from the perspective of anything that referenced the old commit identities directly.

Because every commit hash from the rewritten point forward changes, as covered in Chapter 4, anyone with an existing local clone of the old history now has a copy that has permanently diverged from the newly rewritten, shared version. Simply pulling normally afterward doesn’t cleanly resolve this divergence — it can produce confusing, duplicated history, or merge conflicts stemming purely from the rewrite itself, not from any genuine, new code conflict.

The generally recommended approach is for everyone with an existing local copy to discard it entirely and re-clone the repository fresh after a history rewrite, rather than trying to reconcile their old, diverged copy with the new one. This is precisely why clear, proactive communication — explaining exactly what happened, why, and what each person needs to do — is just as essential a part of a responsible history rewrite as the technical steps themselves.

The core trade-off to internalize: history rewriting trades disruption and coordination effort for a genuine, thorough correction that no other Git operation can provide. It’s the right tool specifically when that thoroughness is truly necessary — and the wrong, needlessly disruptive choice when a simpler, non-rewriting solution like git revert would have been sufficient.

Older history-rewriting approaches often needed to re-examine and reconsider far more of a repository’s history and structure than was strictly necessary for a given filtering task, leading to painfully slow rewrites on large, long-lived repositories — sometimes taking many hours for genuinely large projects. git filter-repo was specifically engineered with a more efficient internal architecture, processing history in a single, well-organized pass and avoiding much of the redundant, repeated work that made earlier approaches so slow.

This performance improvement matters beyond mere convenience: a rewrite that used to take many hours, during which a repository was effectively unusable for normal work, becoming one that completes in a fraction of that time meaningfully reduces the real disruption a necessary history rewrite imposes on an active team.

Because a force-push overwrites a shared branch’s history, restricting who has permission to force-push to important, shared branches is itself a genuine security and stability control, as covered in a related guide on release branches — an accidental or malicious force-push to a critical branch, whether from a rewrite gone wrong or otherwise, can cause serious disruption if not properly guarded against.

It’s also worth understanding that testing any filtering rule thoroughly on a disposable, fresh clone before applying it to a genuinely important repository — exactly as the tool’s own safety design encourages, as covered in Chapter 3 — is not just good practice but a genuine safeguard against the kind of subtle mistake that could otherwise remove the wrong content, or fail to remove the intended content correctly.

The Test-First Pattern always runs a planned rewrite on a fresh, disposable clone first, carefully reviewing the results before ever applying it to a genuinely shared repository — directly following the tool’s own built-in safety philosophy.

The Scheduled-Coordination Pattern treats a necessary history rewrite on a shared repository as a planned event, communicated in advance, rather than something done quietly and unexpectedly, minimizing the disruption covered in Chapter 10.

Common anti-patterns to avoid: the Rewrite-Without-Testing pattern (skipping the fresh-clone testing step and running an unverified rewrite directly against the real, shared repository); the Silent Rewrite (force-pushing rewritten history without warning collaborators, leaving them to discover the disruption on their own); and the Cosmetic Rewrite described above, disrupting an entire team for a benefit that doesn’t justify the real cost.

Common mistakes beginners make: assuming a history rewrite alone is sufficient to neutralize an exposed secret, without also rotating the actual credential; running an untested rewrite directly against an important, shared repository; and force-pushing a rewritten history without first warning collaborators, leaving them to untangle confusing, unexpected conflicts on their own.