Let’s walk through the official BFG Repo Cleaner workflow in detail, explaining exactly what each step does and answering common technical questions about the process. BFG is a fast, user-friendly alternative to tools like git filter-repo for stripping large files, sensitive data, or unwanted blobs from your Git repository’s history—way simpler than the old, clunky git filter-branch.

Step-by-Step Breakdown of the Workflow #

1. Clone a mirrored copy of your repository #

git clone --mirror git://example.com/some-big-repo.git

• Why --mirror? A mirrored clone creates a bare repository that includes every single ref in your repo—branches, tags, stashes, you name it. This ensures BFG can clean all parts of your repository’s history, not just the main branch you’d get with a regular clone.
• Critical note: Never run BFG on your daily working repository. Always use a mirrored copy to avoid accidentally losing uncommitted work or messing up your local setup.

2. Run the BFG tool to clean the repo #

java -jar bfg.jar --strip-blobs-bigger-than 100M some-big-repo.git

• What this does: The --strip-blobs-bigger-than flag tells BFG to hunt down and remove all files (blobs) larger than 100MB from every commit in your history. You can tweak the size (e.g., 50M for 50 megabytes, 2G for 2 gigabytes) or use other flags:
  • --delete-files "*.csv" to remove all CSV files from history
  • --replace-text secrets.txt to redact sensitive data using a list of patterns in secrets.txt
• Prerequisite: You’ll need Java installed on your machine to run the BFG JAR file.
• Quick tip: BFG leaves your latest commit untouched to preserve your current working state. If you want to remove large files from the latest commit too, delete them manually, commit the change, then run BFG.

3. Clean up invalid data with Git GC #

cd some-big-repo.git
git reflog expire --expire=now --all && git gc --prune=now --aggressive

• Breaking this down:
  • git reflog expire --expire=now --all: This clears Git’s reflog (a log of all local changes to your repo’s refs) immediately, instead of waiting for the default 90-day expiration window.
  • git gc --prune=now --aggressive: Git’s garbage collection (gc) removes objects that are no longer reachable (the blobs BFG marked for deletion). --prune=now tells Git to delete these objects right away, and --aggressive runs a deeper cleanup (it takes longer but frees up more space).
• Why this step is non-negotiable: BFG only marks unwanted blobs as "unreachable"—Git won’t actually delete them until garbage collection runs. This step ensures those bloated files are fully removed from your repo.

4. Push the cleaned changes back to the remote #

git push

• Heads up: Since you’ve rewritten your repository’s entire history, this will overwrite the remote repo’s refs. For a mirrored clone, git push will automatically handle pushing all cleaned refs, but you should be aware:
  • Any collaborators with local copies of the repo will need to abandon their local version, clone a fresh copy of the cleaned repo, and reapply any uncommitted work.
  • Coordinate with your team before pushing—rewriting history can cause major conflicts if someone else pushed changes in the meantime.

Common Technical Questions About This Workflow #

Q: Can I run BFG on a regular (non-bare) repository? #

A: You technically can, but it’s not recommended. BFG is optimized for bare/mirrored repos because it avoids conflicts with files in your working directory. If you use a regular clone, make sure you have no uncommitted changes, but the mirrored approach is far safer and more thorough.

Q: What if I need to remove specific files instead of just large ones? #

A: Use the --delete-files flag with a pattern. For example:

java -jar bfg.jar --delete-files "*.log" some-big-repo.git

This will strip all .log files from every commit except your latest one.

Q: Why does BFG leave the latest commit untouched? #

A: The tool is designed to preserve your current working state so you don’t have to re-do recent work. If you need to clean up files in the latest commit, delete them manually, commit the change, then run BFG to handle the rest of the history.

Q: Is BFG better than git filter-repo? #

A: For most common cleanup tasks (like removing large files or sensitive data), yes—BFG is simpler, faster, and has a gentler learning curve. git filter-repo is more flexible for complex custom workflows, but BFG is perfect for the use case you’re working with.

内容的提问来源于stack exchange，提问作者Bill Greer