Working with Git LFS Files
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 in Bitbucket Data Center and Server.
Using Git LFS, you can also lock LFS files to stop others from editing them. This can be helpful if you work with large binary assets that can’t be merged like images, videos, or 3D models.
When files are locked, an icon appears next to them. Hover over it to see who locked the file and when they did this.
To work with Git LFS files you need to know how to:
By default, Git LFS is disabled in Bitbucket for each repository and can only be turned on by repository admins. For more information, see Git Large File Storage.
Installing the Git LFS client
To use Git LFS you first need to install the client on your local machine.
To install the Git LFS client:
1. Check that you have Git 1.8.2 or newer by running:
git --version2. Download and run the Git LFS installer. If you use Linux or Mac OS X you can also use a package manager to install git-lfs.
3. Run this command in a terminal or command prompt:
git lfs installLFS filters will be added to the .gitconfig file in your home directory and will be available for all your repositories. You only need to do this once.
Tracking Git LFS files and making them lockable
Once you’ve installed the Git LFS client, you need to register the folder paths or file types you want it to handle using the track command. If you want to be able to ‘lock’ these files, you must also include the --lockable flag. This needs to be done for each repository.
To track a folder path or file type:
1. Change to the repository directory.
2. Run this command. Note: you can remove the --lockable flag if you don’t need it.
git lfs track '<pattern>' --lockableHere ‘<pattern>’ can be used to match:
A folder path, or paths, such as
'path/to/some/folders/*'.File names, or file types, such as
bckgrnd.bin,'*.psd'or'*.*'.Note: when using wildcards you need to include quotes to stop your shell from expanding them.
The pattern will then be added to the repository’s .gitattributes file.
3. Commit and push the changes to .gitattributes :
git add .gitattributes
git commit -m "add Git LFS to the repo"
git push origin master
You should push the changes whenever you change what files are being tracked so everyone who clones the repo has the tracking patterns.
Now, when you add file names that match the pattern, they will automatically be handled by LFS. You can add multiple patterns this way, and you can see the patterns being tracked using the command, git lfs track.
Locking and unlocking Git LFS files
Once a Git LFS file has been registered as ‘lockable’, it can be ‘locked’ to stop others from editing it while you’re working on it. This can be helpful if you work with large binary assets that can’t be merged.
File locking follows a few rules:
Each file can only be locked by one person at a time.
Locked files can only be unlocked by the person who locked them (see below for how to force unlock files).
If your ‘push’ contains locked files that you didn’t lock it will be rejected.
If your ‘merge’ contains locked files that you didn’t lock it will be blocked.
To lock a Git LFS file:
Change to the repository directory and run the command:
git lfs lock <filename>You can also lock a Git LFS file directly in source view by clicking the Lock button. A lock icon will then be displayed next to the file name.
To unlock a Git LFS file that you locked:
Change to the repository directory and run the command:
git lfs unlock <filename>You can also unlock a Git LFS file directly in source view by clicking the Unlock button. The lock icon displayed next to the file is then removed to indicate an unlocked file.
Unlocking files locked by other people
Locked files in Bitbucket can only be unlocked by the person who locked them, so at times you may need to find out who locked a file so you can ask them for help.
When you try to lock, unlock, push, or merge a locked file that has been locked by another person, the error message will include the username and email address of the person who locked it so you can contact them. You can also run a command to see all locked files in a repository:
To see all locked files:
Change to the repository directory and run the command:
git lfs locksThere may also be times when you can’t ask for a file to be unlocked. For example, the person who locked it may have left your organization. If you find yourself in a situation like this, you can use the force flag to unlock the file.
To force unlock a file:
Change to the repository directory and run the command:
git lfs unlock <filename> --forceMore information
Learn more about using Git LFS at our website, Getting Git Right.