Jacob Allred

Use BFG to completely remove a file from your git repo

Jacob Allred •
#web-dev

I like to keep my blogs in git repos. For small blogs this works great, but for blogs with a ton of images this quickly becomes a problem. For example, my wife’s blog has 4GB of images. git isn’t really designed to handle that.

So I decided to take out the images. Specifically, I decided to exclude wp-content/uploads from her git repo. Just removing the images isn’t good enough, because they are saved in the history of the repo. For a quick and easy way to remove one or more files completely from git, use BFG.

These are the steps I took:

  1. Create a backup of my clone that has all the images in it. Always have a backup when doing something like this.
  2. Remove the files from git without deleting them locally: git rm -r —cached wp-content/uploads
  3. Add wp-content/uploads to my .gitignore
  4. Commit and push the changes.
  5. Download BFG. It is a jar so you’ll need java installed, too.
  6. For convenience, I created an alias in my .bashrc file: alias bfg=‘java -jar /root/bfg-1.11.10.jar’
  7. Clone a bare repo: git clone —mirror git://example.com/some-big-repo.git
  8. Remove references to the images in the repo history: bfg —delete-folders uploads some-big-repo.git
  9. Purge the old files from the repo: git reflog expire —expire=now —all && git gc —prune=now —aggressive
  10. Push your changes into the remote repo: git push

The last step is to clone a fresh copy of the repo. You’ve modified the history of the repo, so you shouldn’t use any existing clones. Be careful not to lose your images! They aren’t in git anymore!

It is important to note that in step #8 you cannot use a full folder path. It won’t let you even if you try. So if you have something else called uploads or with uploads in the path that you’ve previously deleted, it’ll be wiped out, too.

It is also important to note that step #8 won’t do anything if you skip step #2. BFG makes the assumption that you don’t want to get rid of anything that is in your latest commit.

This also works great for removing sensitive information from a repo, for example if you commit a password to a public repo. BFG even lets you search and replace text, so you can simply replace an accidentally committed password with something else instead of deleting the files.