jonlabelle/bfg repository overview

⁠Docker BFG

Current BFG Version: 1.15.0

⁠Table of Contents

• Features⁠
• Usage⁠
• Before You Start⁠
• Examples⁠
  • Complete Workflow⁠
  • Delete specific files⁠
  • Remove folders⁠
  • Replace sensitive data⁠
• More Examples⁠
• Troubleshooting⁠
• Wrapper Functions⁠
  • Bash⁠
  • PowerShell⁠
• My other Docker repos⁠
• License⁠

⁠Features

• All the wonderful features of BFG Repo-Cleaner⁠ without all the setup.
• No Java installation required; Java is bundled within the Docker image.
• Includes the latest version of BFG Repo-Cleaner.
• Uses Eclipse Temurin⁠ JRE for a lightweight environment.
• Multi-architecture support (amd64, arm64).

⁠Usage

Run BFG by mounting your repository directory:

docker run --rm -v /path/to/repo:/work jonlabelle/bfg [options]

Show BFG help:

docker run --rm jonlabelle/bfg --help

⁠Before You Start

1. Backup your repository - Make a complete backup before proceeding
2. Coordinate with your team - Ensure everyone has committed and pushed their work
3. Test on a copy first - Clone a separate copy to test your BFG commands
4. Understand the impact - After force pushing, all team members must reset their local copies
5. Update protected branches - You may need to temporarily disable branch protection rules

⁠Examples

⁠Complete Workflow

Example workflow for removing large files from a repository and syncing across the team:

# Clone the repository as a bare mirror (safer for rewriting history)
git clone --mirror https://github.com/user/repo.git

# Run BFG to remove large files
docker run --rm -v $(pwd):/work jonlabelle/bfg --strip-blobs-bigger-than 100M repo.git

# Enter the repository directory (bare repo's have .git suffix)
cd repo.git

# Clean up and garbage collect
git reflog expire --expire=now --all
git gc --prune=now --aggressive

# Force push changes back to the remote repository
git push --force-with-lease

After pushing, other team members with local clones need to update their repositories:

# Fetch the rewritten history and reset to match the remote
git fetch origin
git reset --hard origin/main

⁠Delete specific files

Remove all files named passwords.txt from history:

docker run --rm -v $(pwd):/work jonlabelle/bfg --delete-files passwords.txt my-repo.git

⁠Remove folders

Remove a folder from all commits:

docker run --rm -v $(pwd):/work jonlabelle/bfg --delete-folders .secrets my-repo.git

⁠Replace sensitive data

Create a replacements.txt file with your replacements, then run:

docker run --rm -v $(pwd):/work jonlabelle/bfg --replace-text replacements.txt my-repo.git

Example replacements.txt format:

PASSWORD1==>***REMOVED***
api_key_12345==>***REMOVED***

⁠More Examples

docker run --rm -v $(pwd):/work jonlabelle/bfg --delete-files '*.{log,zip,db}' my-repo.git

docker run --rm -v $(pwd):/work jonlabelle/bfg --delete-files '*.{pem,key,p12,pfx}' my-repo.git

docker run --rm -v $(pwd):/work jonlabelle/bfg --delete-files '{id_rsa,id_rsa.pub,private.key}' my-repo.git

docker run --rm -v $(pwd):/work jonlabelle/bfg --delete-files '{.env,.env.local,.env.production}' my-repo.git

docker run --rm -v $(pwd):/work jonlabelle/bfg --strip-blobs-with-ids blob-ids.txt my-repo.git

docker run --rm -v $(pwd):/work jonlabelle/bfg --delete-files credentials.json --protect-blobs-from HEAD~5 my-repo.git

docker run --rm -v $(pwd):/work jonlabelle/bfg \
  --strip-blobs-bigger-than 50M \
  --delete-files '{*.key,*.pem,secrets.json}' \
  my-repo.git

For more options and detailed documentation, see the BFG Repo-Cleaner website⁠.

⁠Troubleshooting

cd my-repo.git
git reflog expire --expire=now --all
git gc --prune=now --aggressive
git push --force-with-lease

docker run --rm -v "${PWD}:/work" jonlabelle/bfg [options]

⁠Wrapper Functions

Create a shell function to use BFG like a native command without typing the full Docker command each time.

⁠Bash

Add to ~/.bashrc or ~/.zshrc:

bfg() {
  docker run --rm -v "$(pwd):/work" jonlabelle/bfg "$@"
}

⁠PowerShell

Add to your PowerShell profile:

function bfg {
  docker run --rm -v "${PWD}:/work" jonlabelle/bfg $args
}

⁠My other Docker repos

• jonlabelle/docker-network-tools⁠ — A Docker image with various network tools pre-installed
• jonlabelle/docker-nmap⁠ — Minimal Docker image with Nmap Network Security Scanner pre-installed

⁠License

MIT License⁠