The complete manual for slimming a Git repository and purging secrets

Inheriting an old project often means inheriting a monster repository: a multi-GB .git, ten-minute clones, and secrets buried in history that should never have been committed. We turned one thorough repository cleanup into a manual — every step verifiable, every step reversible.

Step one: find out what's eating the space

Don't guess; measure. From the repository root:

git rev-list --objects --all |
git cat-file --batch-check='%(objecttype) %(objectname) %(objectsize) %(rest)' |
sort -k3 -n -r | head -30

This lists the thirty largest objects in history. In our case: a 700 MB video, three archives, and the remains of countless node_modules.

Step two: rewrite history once confirmed

Use git filter-repo (far safer and faster than filter-branch):

git filter-repo --path big-video.mp4 --invert-paths
git filter-repo --path-glob '*.zip' --invert-paths

Back up a bare mirror first (git clone --mirror). After rewriting, every commit hash changes — that is the nature of rewriting history, not a bug. All collaborators must re-clone or follow the official branch-migration guide.

Step three: committed secrets

Critical order of operations — a secret in history is leaked even if deleted from the latest commit:

1. Revoke and rotate the credential on its platform immediately — before any cleanup;
2. Then remove the file from history with filter-repo;
3. Add it to .gitignore and switch to environment variables or a secrets manager.

Step four: prevent recurrence

• Complete .gitignore from language templates — keep node_modules/, dist/, logs, and large binaries out;
• Server-side repository size alerts and push-size limits;
• Client-side pre-commit hooks scanning for oversized files and secret patterns (AKIA, private-key headers).

Step five: verify

• git count-objects -vH size-pack at a sane magnitude — ours went from 3.1 GB to 190 MB;
• Full clone time from 11 minutes to 40 seconds;
• History search confirms zero hits for the sensitive files.

One closing observation: repositories are like rooms — quarterly small cleanings always beat one massive purge. Run the top-30 size report every quarter and problems stay embryonic.