History rewrite guide

How to permanently remove a secret from git history

You've rotated the key — good. Now comes the part most guides underexplain: actually expunging the secret from every commit that ever contained it, confirming it worked, and coordinating the aftermath. This guide covers the complete workflow with git filter-repo and BFG Repo-Cleaner, the verification steps that prove the rewrite is clean, and what to do about forks and GitHub's object cache.

• Why git rm isn't enough
• Before you start
• Choose your tool
• git filter-repo (recommended)
• BFG Repo-Cleaner
• After the force-push
• Verify it worked
• Common mistakes
• FAQ

Why git rm and committing isn't enough

Git history is an append-only directed acyclic graph. Every commit is a permanent, content-addressed snapshot of your entire project at that moment. When you run git rm .env and push a new commit, you add a commit that removes the file from the working tree — but every previous commit still contains it, intact, with the original content.

Any collaborator can run git checkout <old-sha> -- .env and retrieve the full file with the live key. Any public repository's history is browsable on GitHub at a direct SHA URL. To actually expunge the secret you must rewrite the commit graph — replace every commit that contained it with a new commit that doesn't, giving every affected commit a new SHA.

Before you start

• Rotate the key first. History rewriting is cleanup, not containment. The key must be invalid before you touch git.
• Identify exactly what to remove. Decide whether you are removing an entire file (e.g. .env) or replacing a specific string value (e.g. a key that was hardcoded inline in a source file). The two cases use different tool flags.
• Know your remote branches. Check git branch -r — every branch that contains the secret commit needs to be rewritten and force-pushed. Feature branches are often missed.
• Notify collaborators before pushing. A force-push changes every commit SHA downstream of the rewritten commit. Anyone with an existing local clone cannot simply pull — they must re-clone. Give them time to save any unpushed local work as a patch before you push.

Choose your tool

Two tools are worth using. Avoid git filter-branch — it is deprecated, orders of magnitude slower, and has known correctness issues with complex history.

git filter-repo (recommended)

Install

# macOS
brew install git-filter-repo

# pip (any OS with Python 3)
pip install git-filter-repo

# Verify
git filter-repo --version

Clone fresh — do not use your existing working directory

git filter-repo requires a clean repository with no stale reflogs. Running it on your existing working directory will produce warnings and may require --force, but more importantly, your local reflog references the old commits and can reintroduce them. Always clone fresh:

git clone https://github.com/yourorg/yourrepo.git repo-clean
cd repo-clean

Option A: Remove an entire file from all history

Use this when the secret lived in a dedicated file (e.g. .env, config/secrets.yml, a *.pem key file):

# Remove a single file from every commit on every branch
git filter-repo --path .env --invert-paths --force

# Remove multiple files at once
git filter-repo --path .env --path config/secrets.yml --path id_rsa --invert-paths --force

Option B: Replace an inline string value

Use this when the secret was hardcoded inside a source file that you still want to keep (e.g. const client = new Stripe("sk_live_YOURKEY")). The replacement file maps literal strings to their replacements:

# Create a replacements file (one substitution per line)
printf 'sk_live_YOUR_ACTUAL_KEY_HERE==>***REMOVED***\n' > /tmp/replacements.txt

# Run the replacement across all history
git filter-repo --replace-text /tmp/replacements.txt --force

You can include multiple lines in replacements.txt if several secrets need to be replaced simultaneously.

Add the remote back and force-push

git filter-repo removes the origin remote as a deliberate safety measure — it prevents an accidental push to the original repo before you have verified the rewrite. Add it back explicitly, then push all branches and all tags:

# Add the remote back
git remote add origin https://github.com/yourorg/yourrepo.git

# Push all rewritten branches
git push origin --force --all

# Push all rewritten tags
git push origin --force --tags

BFG Repo-Cleaner

BFG is faster than filter-repo on repositories with many large binary blobs. It requires Java 8 or later.

Download and run on a bare clone

# Download bfg.jar (see https://rtyley.github.io/bfg-repo-cleaner/)
# Requires Java 8+: java -version

# Step 1: Bare clone (BFG requires a bare clone, not a working copy)
git clone --mirror https://github.com/yourorg/yourrepo.git repo.git
cd repo.git

# Step 2a: Delete a file from all history
java -jar bfg.jar --delete-files .env .

# Step 2b: OR replace a specific secret string
# Create replacements.txt with lines like:
# sk_live_YOUR_KEY==>***REMOVED***
java -jar bfg.jar --replace-text /path/to/replacements.txt .

# Step 3: Prune the old unreachable objects
git reflog expire --expire=now --all
git gc --prune=now --aggressive

# Step 4: Force-push
git push --force

After the force-push

Collaborators must re-clone

A force-push rewrites every commit SHA downstream of the rewritten commit. Any collaborator who runs git pull will get a divergence error because their local SHAs no longer match the remote. The only correct action is to delete the local clone and start fresh:

# Collaborators: save any unpushed work as a patch first
git format-patch origin/main  # creates .patch files you can apply later

# Then delete the local clone and re-clone fresh
cd ..
rm -rf yourrepo
git clone https://github.com/yourorg/yourrepo.git

Do not rebase local work onto the new history using old commit SHAs — that will reintroduce the rewritten commits. Apply saved patches or cherry-pick specific changes instead.

GitHub's object cache

After a force-push, the old commits become unreachable — no branch or tag points to them. But GitHub's internal object store retains unreachable objects until its garbage collector runs, which may take up to 90 days for public repositories. During this window, a direct SHA URL (e.g. github.com/yourorg/yourrepo/commit/OLD_SHA) may still resolve and show the old commit content.

For private repositories: open a GitHub Support ticket and request an immediate GC run. GitHub Support can accelerate the cleanup for sensitive data incidents on private repos.

For public repositories: the old objects may remain accessible via direct SHA URL for some time. This is why key rotation is non-negotiable — the rewrite removes the secret from normal access patterns (branches, history browsing), but the key must be invalid before that cache window closes.

Forks are independent repositories

GitHub forks maintain their own complete copy of git history. Force-pushing your repository does not update any fork. Each fork owner must re-clone from your rewritten repository to get clean history. For forks you own on private repositories, run the same filter-repo or BFG workflow independently on each fork and force-push them.

Verify the rewrite actually worked

Do not skip this step. Clone a completely fresh copy of the repository from GitHub (not from your local rewritten copy) and search for the secret across all reachable history:

# Fresh clone from the remote
git clone https://github.com/yourorg/yourrepo.git verify-clone
cd verify-clone

# Search all commit diffs across all branches for the secret value
git log --all -p | grep -n "sk_live_YOUR_SECRET"
# If nothing is returned: the secret is gone from all reachable history.

# Also search the working tree files (in case of inline replacement)
grep -r "sk_live_YOUR_SECRET" . --exclude-dir=.git

# Check stash entries
git stash list
# If any entries exist: git stash show -p stash@{N} to inspect content

If you used --replace-text, also verify the replacement placeholder appears correctly where the old key was:

git log --all -p | grep "REMOVED"

Common mistakes

• Running filter-repo on your existing working directory Your local reflog references old commits. Clone fresh every time — it takes 30 seconds and eliminates a class of errors.
• Forgetting to push tags Tags are refs that point to commits. If a tag points to a commit that contained the secret, the tag still exposes it. Always push with --tags after rewriting.
• Forgetting feature branches --force --all covers all local branches that were fetched. But if you had branches that weren't fetched in your fresh clone, they won't be rewritten. Run git fetch --all before the rewrite to ensure all remote branches are present.
• BFG leaving the HEAD commit unchanged If the secret is still in the most recent commit when you run BFG, it will remain there. Clean the current files with a normal commit first, then run BFG to rewrite historical commits.
• Treating GitHub's cache as "fixed" immediately after pushing The force-push removes the secret from branches and browseable history, but old commit SHAs may still resolve via direct URL for weeks. The key must be rotated before the rewrite, not after.

Frequently asked questions

Before you push: paste the affected file or commit diff into LeakCheck to confirm you've caught every secret in the same file — it's common to find a cluster of credentials together.

Scan with LeakCheck →

More in the LeakCheck guide series

History rewriting is the remediation step after discovery. These guides cover the other moments in the secret-exposure lifecycle:

Also in the Copper Bay Labs ship-safety suite