Use Git LFS with Bitbucket

Bitbucket Cloud supports the Large File Storage (LFS) extension for Git that speeds up the handling of large files. It does this by replacing those large files in your Git repository with text pointer files – the pointers reference the large files, which are actually stored on a remote server. Read more about Git Large File Storage in Bitbucket.

The amount of Git LFS storage you have depends on your Bitbucket Bucket Cloud plan. To see the pricing for the various plans, check out our Bitbucket Cloud pricing page. Get started with Git LFS by completing these steps, described on this page:

Once you've completed these steps, you can carry on working with Git and your repository just as you usually do – all the LFS file handling is completely automatic, and needs no other special actions.

When evaluating Git LFS, we recommend that you use a new repository in Bitbucket. This could be a copy of an existing repository. Don't evaluate LFS with a repository used in production.

1. Create and clone a new repository 

Go to your account in Bitbucket and create and clone a new repo in the usual way.

We recommend that you evaluate Git LFS in Bitbucket using a new repo, to avoid unexpected results in your production or project repos.

2. Install the Git LFS client locally

Each person who wants to use Git LFS needs to install the client on their local machine. They only need to do this once.

Check that you have Git 1.8.2 or later using the git --version command.

Install the Git LFS client:

• For Linux and Mac OS X, use a package manager to install git-lfs, or download from here. 

• On Windows, download the installer from here, and run it. 

Now run the following command in a terminal or Command Prompt:

This adds LFS filters to the .gitconfig file in your home directory, so they are available for all your repos. You could run git lfs install --local if you only want to use LFS with a particular repo.

3. Set up Git LFS file tracking locally

You should set up tracking for each repo that will use Git LFS.

On your local machine:

1. Change directory to the repo you want to use Git LFS with and run this command:

   1 git lfs track '<pattern>'

   The <pattern> can be used to match:

   • A folder path, or paths, such as "path/to/some/folders/*"

   • Particular file names, or file types, such as bckgrnd.bin, "*.psd" or "*.*". Note that it's important to use quotes around wildcards, to stop your shell from expanding those.

   You can add multiple patterns. Use the git lfs track command without arguments to see all the patterns being tracked. The patterns are added to the .gitattributes file for the repo. 

2. Commit and push the changes to .gitattributes in the usual way:

   1 2 3 git add .gitattributes git commit -m "add Git LFS to the repo" git push origin main

   Pushing the changes straight away means that everyone who clones the repo will get the tracking patterns. You should do this whenever you change the tracking.

4. Now push LFS files to Bitbucket

Now you can add files with file names that match the <pattern> and they will automatically be handled by LFS:

Want more? Read our in-depth tutorial about Git LFS and how to use it.