How to move to Git LFS

We’d like to lower size of our git repository. We can do it by rewriting our repository history and store our big, binary files with Git LFS. This document will guide you through this process.

Be aware!

Rewrite of git repository comes with the need of pulling fresh repository by everyone and rebasing branches that did not take part of rewrite (i.e. they were not committed to remote repository before the cleaning process has started).

Identify big files in your repository history

There plenty of solutions how you can find the big files in your project.

This question on stackoverflow is the one


Make sure you have Git LFS installed.

You can download it from its official site.

If you’d like to know more about Git LFS itself, there are two great talks which briefly and fully describes this Git extension.


Actually, part of this guide is also covered in this video.

If you already have big files in your latest commits, move them to LFS before going to rewriting history.

git lfs track "*.zip"

To see what files are already tracked by Git LFS

git lfs ls-files


Once you know which files you’d like to be handled by Git LFS, we can proceed to the next step - rewriting repository history.

We’re going to use BFG tool for this task. Install Java SDK and download BFG tool from their official site.

Why BFG? Because it’s fast, easy and reliable. We could do the same with git-filter-branch, but we simply don’t want to.

See BFG vs git-filter-branch comparison.

You should have been able to print help tip for bfg.jar.

PS> java -jar bfg.jar /?
bfg 1.13.0
Usage: bfg [options] [<repo>]

Move files to Git LFS

Firstly, you have to clone your repository to your disk as mirror.

Let’s assume we’re working on NEP repository.

git clone --mirror nep.git

The nep.git is the .git directory you regularly see in your repository when you pull your repository. Size of freshly mirrored repository is the actual size of the repository.

Now, let’s run BFG on NEP mirror. We’re going to make files with specified extension to be handled by Git LFS.

java -jar bfg.jar --convert-to-git-lfs '*.{bak,nupkg,dll,zip}' --no-blob-protection nep.git

To read more about used commands, print BFG help.

Then run some cleaning (suggested by BFG itself)

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

And our work here is done.

From now on, all specified files should be handled by Git LFS.


  1. Firstly check your nep.git directory size, it should decrease.
  2. Secondly, you should try out if your repo didn’t break during the process. Clone your local repository mirror and try building your repository.
    git clone nep.git nep-repo cd nep-repo
    If all's fine, we're good.
  3. You can check Git LFS configuration in .gitattributes

Push changes back to remote

To complete the process, we have to update our remote with new commits.

git push --all --force

Looks scarry, isn't it? It swaps everything on your remote with your local repository, so make sure you have back it up.

Enable Git LFS on BitBucket

BitBucket has nice-to-have feature with better support of Git LFS.
You can find it in BitBucket project settings.

comments powered by Disqus