Products
Get started
Documentation
Resources
Atlassian Support
/
Bitbucket
/
Resources
/
Set up and work on repositories in Bitbucket Cloud
/
Manage large files with Git Large File Storage (LFS)
Cloud

Use BFG to migrate a repo to Git LFS

BFG and the BFG Repo-Cleaner are third-party utilities that are not supported by Atlassian. The material provided in this support document is for educational purposes only and is not intended to be a process or resource that is supported by Atlassian or Bitbucket Cloud. Have questions? Please check the Git LFS support release notes or the BFG Repo-Cleaner page.

It's important to realize that:

  • BFG will completely rewrite the Git history for the repo.

  • The entire migration process can take a while, during which time you and any members of your workspace should stop working with the existing repository.

  • There is no guarantee that migrating to Git LFS with BFG will reduce the repository size reported on Bitbucket Cloud, even if size is reduced locally. This is because Bitbucket Cloud stores additional references to git commits that are not visible in a clone, in order to preserve the diff of merged pull requests. To have these references identified and removed from Bitbucket Cloud storage, you will need to contact our Support team. Note that removing any references may lead to the deletion of historic pull request data.

When you want to use the Git LFS extension with large files that already exist in a Bitbucket repo, just tracking those large files does not convert them to LFS files. Because the large files are still part of the Git history, the only way to convert those files is to rewrite the history. 

This page describes the three stages involved when using bfg-repo-cleaner to change the Git history of a repo in Bitbucket.

Before starting the migration, ensure that:

  • You have enough LFS storage for the files you want to convert. This needs to fit the files as they are now, and at all times in past history.

  • Everyone with access to the repo has pushed all changes. Any work that has not been pushed will be impossible to merge later.

  • You use repo permissions to prevent anyone from pushing new work while the migration is happening.

  • You have the Java Runtime Environment  (Java 7 or above) installed on your local machine.

  • You've downloaded latest BFG version from https://rtyley.github.io/bfg-repo-cleaner/.

Have questions? Please check the Git LFS support release notes or the BFG Repo-Cleaner page.

A. Convert the existing files in your repo to Git LFS

Run all of the following commands from the terminal.

1. Clone the repo

Cloning with the mirror flag gives you a bare repository. Do this to ensure you get all the branches from you and your colleagues.

This will create a folder called <repo-name>.git

2. Back up the cloned repo

Make a backup of the  <repo-name>.git folder so if anything goes wrong you can revert to this version.

3. Convert the Git history with BFG

Make sure you've downloaded latest BFG version from https://rtyley.github.io/bfg-repo-cleaner/.

Use the absolute path to the location of the downloaded bfg-x.x.x.jar file.

This example converts png and mp4 file types, but you can specify other file types to convert as well.

 This will rewrite all the history of all the branches, replacing all the png or mp4 files with LFS versions.

4. Initialize Git LFS

This adds the pre-push hook to the bare repo.

5. Push the converted repository back to Bitbucket

This will push all your large files to the LFS storage, then overwrite your Git history with the new rewritten history.

Have questions? Find more on the BFG Repo-Cleaner page or the Git LFS support release notes.

B. Set up tracking for future files in Git LFS

1. Clone the converted repo from Bitbucket:

This will clone the previously converted Git repo.

2. Track files in Git LFS

See set up Git LFS file tracking locally. 

C. Let members of your workspace change to the updated repo

Each person needs to have installed the Git LFS extension locally. See the instructions on Use Git LFS with Bitbucket. 

Then they must delete their existing local clone of the repository and clone the new LFS-enabled version:

Still need help?

The Atlassian Community is here for you.
Ask the Community
On this pageA. Convert the existing files in your repo to Git LFS1. Clone the repo2. Back up the cloned repo 3. Convert the Git history with BFG 4. Initialize Git LFS5. Push the converted repository back to BitbucketB. Set up tracking for future files in Git LFS1. Clone the converted repo from Bitbucket:2. Track files in Git LFSC. Let members of your workspace change to the updated repo
CommunityQuestions, discussions, and articles