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:
It's important to realise that:
- BFG will completely rewrite the Git history for the repo.
- The entire migration process can take a while, during which time you and your team should stop working with the existing repo.
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/.
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 team mates.
This will create a folder called
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
This example converts
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
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.
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
C. Let your team 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: