How to Clean Git History from Secrets Using BFG Repo-Cleaner (Ubuntu-Friendly Guide)

🔒 How to Clean Git History from Secrets Using BFG Repo-Cleaner (Ubuntu-Friendly Guide)

Have you ever accidentally committed secrets like database credentials or API keys to your Git repository? Don’t panic — you can clean your repo history and protect your sensitive data.

In this post, I’ll walk you through using BFG Repo-Cleaner to scrub secrets from Git history — with simple step-by-step instructions and working commands for Ubuntu Linux users.

---

⚠️ Why This Matters

Once a secret is committed, it lives in your Git history. Even if you delete the line or file, it’s still retrievable unless you rewrite the history.

---

🧰 Tools We’ll Use

• BFG Repo-Cleaner – a fast alternative to git filter-branch
• Git
• Java Runtime (required to run the BFG .jar)

---

🐧 Step-by-Step Guide (Ubuntu Linux)

✅ Step 1: Install Java

BFG requires Java to run:

sudo apt update
sudo apt install default-jre -y

---

✅ Step 2: Download BFG Repo-Cleaner

Grab the latest .jar from Maven Central:

wget https://repo1.maven.org/maven2/com/madgag/bfg/1.14.0/bfg-1.14.0.jar -O bfg.jar

You can now run it via:

java -jar bfg.jar --help

---

✅ Step 3: Clone Your Repository in Mirror Mode

git clone --mirror https://github.com/your-username/your-website.com.git
cd your-website.com.git

The –mirror option ensures we get all refs and branches for complete cleanup.

---

✅ Step 4: Define Secrets to Remove

Create a secrets.txt file with strings you want to remove from the entire history:

DB_PASSWORD
DB_USERNAME
google_recaptcha_secret
my_old_secret_key

🔐 These can be full strings or patterns. BFG will replace them with [REMOVED].

---

✅ Step 5: Run BFG

java -jar ../bfg.jar --replace-text secrets.txt

Or to delete sensitive files completely (e.g., .env):

java -jar ../bfg.jar --delete-files .env

---

✅ Step 6: Cleanup and Optimize

After BFG has done its job, run the following to clean and compact the repo:

git reflog expire --expire=now --all
git gc --prune=now --aggressive

---

✅ Step 7: Force Push the Cleaned Repo

⚠️ This rewrites history, so collaborators must re-clone the repo afterward.

git push --force

---

✅ Bonus: Make BFG Globally Available (Optional)

sudo mv bfg.jar /usr/local/bin/bfg.jar
echo 'alias bfg="java -jar /usr/local/bin/bfg.jar"' >> ~/.bashrc
source ~/.bashrc

Now you can run BFG anywhere with:

bfg --help

---

🔎 How to Verify That Secrets Are Gone

Use Git’s search to confirm:

git log -S'some_secret_string'

---

🚨 Don’t Forget to Rotate Secrets

Even after removing secrets from history, treat them as compromised and rotate them immediately (update DB users, regenerate API keys, etc.).

---

📦 Alternatives to BFG

If you’re working on more complex history rewrites, also consider:

[git filter-repo] – the official successor to filter-branch
[git filter-branch] – powerful but slow and error-prone

---

🤝 Conclusion

Mistakes happen, and leaking secrets in Git is more common than you’d think. Luckily, tools like BFG make it fast and easy to clean your repo and start fresh.

If you found this helpful, share it with your team or developer community — and let’s keep our code (and secrets) safe. 🛡️