Removing large binaries from Git history with git filter-repo

Goal

Reduce the size of a repository whose history contains large binaries (build outputs, media, database dumps, or a secret that must disappear) so that clones and fetches become fast again.

Prerequisites

git filter-repo installed (the git-filter-branch documentation itself recommends it as the alternative and marks filter-branch as not recommended). Permission to force-push every branch and tag, and a way to reach every collaborator and CI system. A quiet period in which nobody pushes.

Steps

1. Measure first: git count-objects -vH shows the pack size; git rev-list --objects --all | git cat-file --batch-check='%(objecttype) %(objectname) %(objectsize) %(rest)' | sort -k3 -n | tail -20 lists the largest blobs with their paths. git filter-repo --analyze writes reports on paths and blob sizes without modifying the repository.
2. Decide what goes: whole paths (--path build/ --invert-paths), blobs above a size (--strip-blobs-bigger-than 10M), or specific blob IDs. Move files that are still needed into LFS or an external store before the rewrite.
3. Work in a fresh clone (git clone --mirror or a plain clone). The manual states that filter-repo aborts when run in a repository that is not a fresh clone, to protect history that exists nowhere else.
4. Run the rewrite, for example git filter-repo --strip-blobs-bigger-than 10M --path assets/raw/ --invert-paths. Review the result: git log --stat, the largest-blobs listing again, and a build from the rewritten tree.
5. Announce the cutover with a date. Pause CI and block pushes.
6. Push the result. The manual states that filter-repo removes the origin remote to push people towards a new repository; either push to that new remote and retire the old one, or re-add origin and run git push --force --branches --tags --prune as the manual shows.
7. On the server, expire reflogs and run garbage collection, or use the hosting platform's cleanup function; until then the old objects remain reachable and the size does not drop.
8. Every collaborator re-clones. Existing clones that merge or rebase old branches will push the old objects straight back.

Expected result

Pack size is down to the size of the remaining content; old commit IDs no longer resolve; open pull requests have been rebased onto the rewritten branches.

Limits and test basis

A rewrite is destructive and global: signatures on the old commits do not carry over to the rewritten ones (a signature covers the old content), references in tickets and commit messages point at IDs that no longer exist (filter-repo can create replace refs and message rewrites to soften this), and forks keep the old history. A removed secret must still be rotated; copies may exist elsewhere. Steps follow the cited manuals; no sizes or durations are claimed.

Deciding whether a rewrite is needed at all

Before step 1, decide which of three conditions holds: the server refuses or throttles the repository (a size quota or push limit), the objects must not exist anywhere (a secret, a licensing problem), or the host does not support partial clone. If none applies and the motive is clone time, configure partial clone instead: git clone --filter=blob:none or --filter=blob:limit=1m gives developers and CI a fast clone without rewriting history, invalidating pull requests or forcing anyone to re-clone; the large objects stay on the server, which is usually acceptable. Reserve the rewrite for the three cases above, and even then rotate any secret first, since the rewrite only removes the copies you control.