Git Large File Storage
Git Large File Storage (LFS) is a Git extension that improves how large files are handled. It replaces them with tiny text pointers that are stored on a remote server instead of in their repository, speeding up operations like cloning and fetching.
Bitbucket Data Center ships with Git LFS enabled at an instance level, but disabled for each repository. It also includes an embedded LFS object store, removing the need for an external one. Learn more about Git LFS
On this page
Important Notices
HTTP(S) must be enabled
Git LFS supports SSH remotes, but downloading and uploading objects is done via HTTP(S). If SCM connections to Bitbucket over HTTP(S) are not enabled, Git LFS will not work.
The Bitbucket base URL should also be configured to a HTTP(S) URL.
We recommend configuring SSL
If your instance is available over the internet, usernames, passwords, and other data may be at risk. See Proxy and secure Bitbucket for more info.
The Data Center Migration Tool does not export Git LFS
For more information see LFS Migration.
Enable Git LFS for a repository
Git LFS is disabled by default.
To enable Git LFS:
- Go to Repository settings > Large file storage (LFS).
- Select Allow LFS.
- Select Save.
If you cannot select Allow LFS, this is because the instance administrator has disabled LFS support on the instance.
Install and use the Git LFS command line client
Git LFS aims to integrate with the standard Git workflow as seamlessly as possible.
To push your first Git LFS files to an existing repository:
- Enable Git LFS support for the repository (see above).
- Download and install the git-lfs command line client.
Install the Git LFS filters:
git lfs installThis adds the following lines to the
.gitconfigfile located in your home directory:[filter "lfs"] clean = git-lfs clean %f smudge = git-lfs smudge %f required = trueThe above change applies globally, so it is not necessary to run this for each repository you work with.
Choose the file types you would like LFS to handle by executing the
git lfs trackcommand. Thegit lfs trackcommand creates or updates the.gitattributesfile in your repository.
Change to your cloned repository, then executegit addto ensure updates to the.gitattributesare later committed:git lfs track "*.jpg" git add .gitattributesAdd, commit, and push your changes as you normally would:
git add image.jpg git commit -m "Added an image" git pushWhen pushed, the Git tree updates to include a pointer to the actual file content. This pointer will include the SHA256 hash of the object and its size in bytes. For example:
oid sha256:4fa32d6f9b1461c4a53618a47324e243e36ce7ceae72ad440cc811a7e6881be1 size 1580060The object itself will be uploaded to a separate location via the Git LFS Batch API. Specifically, the object will be uploaded to an embedded LFS object store within your Bitbucket instance.
Disable Git LFS
Git LFS support is enabled by default. It can, however, be disabled. This will prevent upload or download of LFS objects for all repositories, but it won't delete existing LFS objects stored within Bitbucket.
To disable Git LFS:
- Log in with sysadmin permissions.
- Go to
> Server settings. - Untick Git LFS enabled.
- Select Save.
Embedded Object Store
Bitbucket includes an embedded LFS object store. Uploaded Git LFS objects are stored in the directory $BITBUCKET_HOME/shared/data/git-lfs/storage. This storage location cannot be changed, as for clustered deployments it is critical that LFS object storage reside on the shared filesystem so it is globally visible to all cluster nodes.
Repository Forking
LFS enabled repositories support forking and a full fork-based workflow including pull requests between forks and fork synchronization. Forking is implemented through sharing of objects between fork and origin repositories and as such forks are lightweight. This means creating a fork is faster because objects are not duplicated when a fork is created.
Resolution of merge conflicts is slightly different from the non-LFS case, specifically where a merge conflict exists between two LFS objects. Since the Git repository simply contains an LFS pointer, conflict resolution must be performed with the conflicted pointer file.
Such a conflict might look like this:
Users are still required to resolve the merge conflict manually using the command line Git client, as they normally would. The merge strategy, since this is only a pointer, can only be an ours or theirs based strategy, keeping one or the two pairs (oid/size). When resolving the conflict, if the pointer file becomes corrupted it will not be recognized as an LFS file.
Smart Mirroring
Mirrors supports mirroring of Git LFS objects as of Bitbucket 4.5. Mirroring of Git LFS objects is performed on-demand; that is, when a client requests download of a Git LFS object from the mirror node, the object will be streamed from the upstream node if it is not already available on the mirror. Subsequent downloads of the same object will be downloaded directly from the copy stored on the mirror.
Limit Disk Space Usage
By default Bitbucket won't permit Git LFS uploads if the amount of free disk space in the filesystem that hosts the storage directory has less than 100 megabytes of free disk space. When a client attempts to upload (via a Git push) an LFS file that would result in the free disk-space threshold being exceeded, an error message indicating as such is sent to the client:
$ git push
Git LFS: (0 of 1 files, 1 skipped) 0 B / 348.59 MB, 348.59 MB skipped
[a39717817507d0ae3434a36347159e4970aec061c8c506f197c0eeadd2e8efe2] Insufficient free space in store
error: failed to push some refs to 'https://bitbucket.example.com/bitbucket/scm/myproject/myrepo.git'A warning will also be logged in the atlassian-bitbucket.log file. For example:
2016-01-01 18:00:00 WARN [http-nio-7990-exec-2] user @G6I7R6x969x556x0 0:0:0:0:0:0:0:1 "POST /scm/myproject/myrepo.git/info/lfs/objects/batch HTTP/1.1" c.a.b.i.s.g.l.s.e.EmbeddedStoreAccessor Upload rejected due to insufficient free space in store - Required: 1073741824 Free: 10485760The free disk-space threshold can be tuned by adding the following property to the config properties file (this example tunes the threshold to one gigabyte, and note that this value is in bytes):
plugin.bitbucket-git-lfs.minimum.free.space=1073741824Setting the value to zero will disable the free disk space check and will allow files to be uploaded even if doing so would exhaust all available disk space. This however is not encouraged, it can lead to situations where the system exhausts all disk space but is unable to log error messages stating the same (because the disk is full), leading to difficulties debugging problems that are caused by disk space exhaustion.
plugin.bitbucket-git-lfs.minimum.free.space=0Bitbucket must be restarted for the change to take effect.
Limit Network Connections
Large Git LFS download or upload operations over very slow network links could take many minutes, or even hours. Bitbucket supports a finite number of HTTP connections (by default 200). If Git LFS were permitted to exhaust this connection pool then the user interface, Git hosting, and REST API access could be impacted. For this reason a default limit of 80 concurrent Git LFS connections are permitted. This limit can be increased or decreased if necessary by overriding the throttle.resource.git-lfs= setting in the config properties file. Bitbucket must be restarted for the change to take effect.
When a client makes a request to upload or download an object, and the request would exceed the maximum number of concurrent connections, a HTTP status 503 is returned, and this error is sent to the client:
The requested resource is busy and cannot service your request. Please try again laterThe atlassian-bitbucket.log file will also contain an associated warning:
2016-01-01 18:00:00 WARN [http-nio-7990-exec-3] username @1HJ1OF1x1115x417x1 0:0:0:0:0:0:0:1 "GET /rest/git-lfs/storage/myproject/myrepo/3a9219fde5bc436a2fc37cdd38bdb8478a210c7a49405dd9603ccdc95ed39613 HTTP/1.1" c.a.s.i.t.SemaphoreThrottleService A [git-lfs] ticket could not be acquired (0/80)