BFG を使用してリポジトリを Git LFS へ移行する

既存の Bitbucket リポジトリで Git LFS を使用する


Still need help?

アトラシアン コミュニティをご利用ください。


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

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

Run all of the following commands from the terminal.

1. Clone the repo


git clone --mirror<username>/<repo-name>.git


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 <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

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

java -jar <path to>bfg-x.x.x.jar --convert-to-git-lfs "*.{png,mp4}" --no-blob-protection <repo-name>.git

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

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

4. Initialize Git LFS


cd <repo-name>.git
git lfs install


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

5. Push the converted repository back to Bitbucket


git push --force


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:

git clone<username>/<repo-name>.git

This will clone the previously converted Git repo.

2. Track files in Git LFS

See set up Git LFS file tracking locally


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:


git clone<username>/<repo-name>.git
最終更新日 2017 年 7 月 18 日


Powered by Confluence and Scroll Viewport.