Working on any project, it is super important to make sure that your data is safe and protected. And sometimes even when you’re are having everything under control, unpleasant incidents still happen.   Let’s take repositories. Any sensitive data saved in your repository may be the beginning of a disaster. To prevent the catastrophe, make sure to delete all security-related information about your projects such as API keys, passwords, or just any large files from .git repository. In my case, I had to remove 650 MB file. Its size was too large for normal functioning of Gitlab mirror. The problem is that by sending files from GitLab to GitHub, the GitHub platform rejects the updated mirror because it does not let uploading files larger than 100 MB. So, eventually, Gitlab mirror stopped working.

How to remove a file from git commit history?

It would be logical to just delete this file and go on committing & merging the branch without it. Yet, it won’t solve the problem. The file’s reference will still be saved in the repository history and, as in my case, the Gitlab mirror won’t still work. So, what to do next?

BFG Repo-cleaner

Use BFG Repo-cleaner. It’s a tool that helps to delete a file from git repo history. It’s best suited to remove large files and security information such as passwords, credentials & private files. BFG Repo-cleaner is quite simple and fast to use. With this tool, developers can also shrink their repositories without any additional troubles. The detailed instruction on how to remove a file from Git repo history via BFG Repo-cleaner you can check here. Yet, while using BFG Repo-cleaner to remove a large file from git commit history, I faced a number of pitfalls and had to do some actions twice. So, here are some tips on how to avoid these possible traps.

9 Steps to Remove files via BFG Repo-cleaner easily

  1. Before starting the procedure, make sure you have Java Runtime Environment installed on your machine. If you don’t, you should install Java Runtime Environmentat first.
  2. After this, download BFG as well. If you need to download it on macOS, try doing it via brew install bfg.
  3. Create cd YOUR_WORKING_DIRECTORY in the terminal. Since .git repository will be cloned here, YOUR_WORKING_DIRECTORY must not be a targeted repo which you will use. For example, if all repos are in the ‘Work’ file, then simply create cd Work/.
  4. Next Step is to clone a repo with --mirror flag.
  5. Then, drop what you need with bfg --delete-files <PATH_TO_HUGE_FILE> blablabla.git command.
  6. Next, go inside the cloned .git repository ― cd blablabla.git. You should not go into the original repository, but in its mirror, which you’ve cloned in Step 4.
  7. You may need to edit your repository settings in case you protect your branches for pushing. Then you can push git push.
  8. Once you’ve done it, all team members should delete the local repositories and clone it again with the new .git history.
  9. Apart from the repository itself, in your directory, chosen in Step 3, you can delete the remained stuff: m -rf blablabla.git and rm -rf blablabla.git.bfg-report/.


Security should always be of the top priority. That’s how we see it in Fulcrum. In everything that you’re doing. Starting from big projects to such routine actions as simply working in the repository. That’s why we always stick to the highest security standards to provide the best quality and the most pleasant experience for our clients.