Get started with Bitbucket Cloud
New to Bitbucket Cloud? Check out our get started guides for new users.
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 the 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
1
git clone --mirror git@bitbucket.org:<username>/<repo-name>.gitCloning 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.
1
java -jar <path to>bfg-x.x.x.jar --convert-to-git-lfs "*.{png,mp4}" --no-blob-protection <repo-name>.gitThis 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
1
2
cd <repo-name>.git
git lfs installThis adds the pre-push hook to the bare repo.
5. Push the converted repository back to Bitbucket
1
git push --forceThis 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:
1
git clone git@bitbucket.org:<username>/<repo-name>.gitThis 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:
1
git clone git@bitbucket.org:<username>/<repo-name>.gitWas this helpful?