Use Git LFS with existing Bitbucket repositories

This page describes how to use the Git LFS (Large File Storage) extension with an existing Bitbucket Cloud repository:

If you don't have a repo in Bitbucket yet, see our Use Git LFS with Bitbucket page to get started.

Start using Git LFS with an existing repository

1. Install the Git LFS client on your local machine

See the instructions on Use Git LFS with Bitbucket.

2. Set up Git LFS file tracking locally

See the instructions on Use Git LFS with Bitbucket.

3. Change the Git history

It's important to note that just tracking large files does not convert them to LFS files. Because the large files are still part of the Git history, the only way to convert those files is to rewrite the history. 

Use bfg-repo-cleaner to convert your existing Git repository to use Git LFS – follow our instructions at Use BFG to migrate a repo to Git LFS.

Delete Git LFS files from a repository

There may come a time when you want to delete Git LFS files from a repo, perhaps because you want to reclaim LFS space in your Bitbucket account. Note that you'll be able to get more storage capacity once the new Bitbucket pricing model has been rolled out.

Delete individual LFS files from your repository

It's important to understand that:

• The delete operation described here is destructive – there's no way to recover the LFS files referenced by the deleted LFS pointer files (it's not like the git remove command!) – so you'll want to back up the LFS files first.

• Deleting an LFS file only deletes it from the remote storage. All reference pointers stored in your Git repo will remain. 

• No branch, tag or revision will be able to reference the LFS files in future. If you attempt to check out a branch, tag or revision that includes a pointer file referencing a deleted LFS file, you'll get a download error and the check out will fail. 

• When using the BFG tool, only the pointers in the core repository are deleted. The actual LFS file in the repository is not deleted.

A repository admin can delete Git LFS files from a repo as follows:

1. Go to the Settings page for the repo and click Git LFS to view the list of all LFS files in that repo.

2. Delete the LFS files using the actions menu.

Delete the entire repository that includes LFS files

• Make sure that you have a full backup of your repository including all LFS files before you delete your repo.

• A repository admin can delete the entire LFS repo from the repo settings.

• To see how much LFS storage each repo consumes go to Git LFS in your account settings in Bitbucket.

How to avoid download errors...

You can skip download errors by changing your .gitconfig file or by adding a variable. This causes Git LFS not to abort the smudge filter when a download error is encountered, which allows actions such as a checkout to work when you are unable to download the LFS content. LFS files which could not download will contain pointer content instead.

Note that this will result in Git commands that call the smudge filter to report success even in cases when LFS downloads fail, which may affect scripts or build systems.

Change your .gitconfig file

Add the following line to your .gitconfig file:

Variable

You can also set the variable GIT_LFS_SKIP_DOWNLOAD_ERRORS=1 to get the same effect.