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.

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 repo in Bitbucket. This could be a copy of an existing repository. Don't evaluate LFS with a repo 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:

git lfs install

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:

    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:

    git add .gitattributes
    git commit -m "add Git LFS to the repo"
    git push origin master

    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:

git add <someLFSfilename>
git commit -m "Add LFS file"
git push origin master


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


Was this helpful?

Thanks for your feedback!

Why was this unhelpful?

Have a question about this article?

See questions about this article

Powered by Confluence and Scroll Viewport