Current limitations for Git LFS with Bitbucket
This page describes workarounds for the following limitations when using Git LFS for Bitbucket.
Repositories can not be transferred
|The limitation||Currently, the transfer of repositories with Git LFS files is disabled.|
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.
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:
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.|
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.
When you fork a repo, you can use the command line to transfer the Git LFS files to the new repo, as follows:
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.|
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:
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
|The workaround for a branch||
The workaround is to manually clone the repo, check out the branch, then archive it locally:
|The workaround for a tag||
The workaround is to manually clone the repo, check out the tag, then archive it locally:
Deployment keys do not allow access to the Git LFS files
|The limitation||Currently, deployment keys do not allow access to Git LFS files. If another application, such as a build system, uses deployment keys to run builds on a branch that contains LFS files, the build will fail.|
|The explanation||Deployment keys are currently unable to give read permissions for Git LFS files (which are stored remotely). Any other system that relies on the ability to read all the repository files will fail.|
The recommended workaround is to set up an App password to give another application read access to the repo.
Note that the App password provides read access to all the repos that you have access to read and is tied to your individual account's credentials. Read more about App passwords.
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!
Was this helpful?
Thanks for your feedback!