Current limitations for Git LFS with Bitbucket

This page describes workarounds for the following limitations when using Git LFS for Bitbucket.

Note that there's no limit on the LFS file size you can push to Bitbucket Cloud.

Repositories can not be transferred

The limitation

Currently, the transfer of repositories with Git LFS files is disabled.

The explanation

Transferring a repo does not give the new owner permissions to access the Git LFS files, so all references to those files in the repository become broken. Furthermore, some metadata, such as for issues and pull requests, are not correctly transferred to the new repo.

Once any user pushes the first LFS file to the repo, then transferring of that repo is disabled.

The workaround

Instead of transferring the repo, you can clone the repo to your local machine, then create a repo in Bitbucket, and push to that.

When you do this, all files and the Git history will be available in the new repo, but the metadata for such things as issues, pull requests won't be copied over. Furthermore, you'll have to set up users and access permissions for the new repo.

Proceed as follows:

  1. Clone the Git LFS repo to your local machine as usual:

  2. Fetch the Git LFS history:

    1 git lfs fetch --all origin
  3. Create a new repo in Bitbucket. 

  4. Add a remote locally that points to the new repo:

    1 git remote add new-origin <URL to new repo>
  5. Now push to the new repo:

    1 git push -u new-origin --all

    This pushes the repo and its refs for the first time.

  6. Push Git LFS data to the new repo:

    1 git lfs push --all new-origin
  7. Finally, update the remotes for the new repo:

    1 2 git remote set-url origin <URL to new repo> git remote set-url --push origin <URL to new repo>

     

Git LFS files are not copied when a repo is forked

The limitation

Currently, when you fork a repo that has Git LFS files, the LFS files are not copied to a new remote store.

The explanation

Forking a repo that has Git LFS files copies all files to the fork as usual, including the LFS pointer files. However, the pointer files still point to the original remote store, but the new repo doesn't have permissions to access that.

Once any user pushes the first Git LFS file to the repo, then this limitation applies to forking of that repo.

Note that cross-fork pull requests are affected, for the same reason – LFS files are not copied to the remote store when the pull request is merged.

The workaround

When you fork a repo, you can use the command line to transfer the Git LFS files to the new repo, as follows:

  1. Fork the repo as usual in Bitbucket.

  2. Now, clone the new repo to your local machine:

    1 git clone <clone URL for forked repo>

    You're may to see errors – we're going to fix those below.

  3. Add a remote that points to the original repo:

    1 git remote add old-origin <URL to original repo>
  4. Fetch the Git LFS data from the original repo:

    1 git lfs fetch --all old-origin
  5. Push the Git LFS data to the new repo:

    1 git lfs push --all origin
  6.  Pull from the new repo to update the clone:

    1 git lfs pull

    You're done!

Repository archives do not include the Git LFS files

The limitation

Currently, Git LFS files are not included when you download an archive of a repository, tag or branch. Other than the usual source files, only the pointer reference files for LFS files are included. This means that archiving does not create a full backup for you.

The explanation

Although the Git LFS pointer files are included in the archive, the LFS files are not currently added.

Once any user pushes the first LFS file to the repo, then this limitation applies to archives made of that repo.

The workaround for a repo

The workaround is to manually clone the repo and archive it locally:

  1. Clone the repo:

    1 git clone <URL for repo>
  2. Manually archive the repo directory locally using your favorite tool.

  3. (Optional) Upload the archive to the Downloads page in Bitbucket.

Note that doing this will only archive the files currently in the head of the main branch. To get all the LFS files ever referenced in the Git history you'll need to use git fetch --all before creating the archive.

The workaround for a branch

 The workaround is to manually clone the repo, check out the branch, then archive it locally:

  1. Clone the repo:

    1 git clone <URL for repo>
  2. Check out the branch:

    1 git checkout <branch_name>
  3. Manually archive the repo directory locally using your favorite tool.

  4. (Optional) Upload the archive to the Downloads page in Bitbucket.

The workaround for a tag

 The workaround is to manually clone the repo, check out the tag, then archive it locally:

  1. Clone the repo:

    1 git clone <URL for repo>
  2. Check out the tag:

    1 git checkout tags/<tag_name>
  3. Manually archive the repo directory locally using your favorite tool.

  4. (Optional) Upload the archive to the Downloads page in Bitbucket.

 

Avoid the Git LFS limitations completely

If the Git LFS limitations in Bitbucket or the workarounds are too restrictive, a repository admin can remove all Git LFS files from the repo to restore the standard Git behavior.

See Use Git LFS with existing Bitbucket repositories for instructions, and the caveats!

Git LFS lock is not supported on Bitbucket Cloud

At this time, Bitbucket Cloud does not support Git LFS lock functionality. For more information or to vote for or leave feedback on the current enhancement request, see Git LFS (v2.x) File Locking Support.

Additional Help