About Git LFS
Git is not good at handling large files such as audio, video, and high-quality images, especially when such files are updated regularly, as every version of the files will be downloaded or uploaded by the git client. If you have such large files in your Git repository, the typical git processes like git clone, git push, and git pull, etc, can take a long time.
Git LFS（Large File Storage, LFS) is a Git extension developed by GitHub, Microsoft, Atlassian, and other contributors to solve the problems caused by large files, making it possible to handle them more efficiently.
Download large files only when you need them
Large files tracked by LFS will be downloaded only when they are needed during git checkout, and not during git clone or git pull. This means that less data is downloaded and cloning/fetching from repositories handling large files is faster.
Large files are managed and stored outside of the remote Git repository
Git LFS does not store large files in the user's remote repository; it only stores the file's metadata or pointer which is used by the LFS server to manage the file.
Using Git LFS will help to keep the Git repository within 1GB which is a general recommendation for maintaining Git performance.
Installing LFS
LFS is provided as an extension for the Git command, so you need to download the LFS package and install it. The following is the installation method for each operating system.
Mac
- Run brew update
- Run brew install git-lfs
- Run git lfs install
Windows
- Download the installer for Windows.
- Run the installer for Windows.
- Run git lfs install
Basic Usage of LFS
This section explains the basic usage of LFS.
To track files with LFS, you need to set the target file pattern in each repository.
Adding files to be tracked by LFS
Execute the following command in the target repository:
$ git lfs track [<pattern>]
You can add files to be tracked by matching them using a <pattern>.
The following pattern is an example of specifying only a single file:
$ git lfs track "foo/bar/baz.png"
The following pattern is an example of specifying all the files in a single directory:
$ git lfs track "foo/bar/*"
The following pattern is an example of specifying all files with a single extension:
$ git lfs track "*.png"
You can also display all tracked patterns that have been previously set, with the command:
$ git lfs track
Listing tracked patterns
foo/bar/baz.png (.gitattributes)
foo/bar/* (.gitattributes)
*.png (.gitattributes)
These settings are stored in the .gitattributes file:
foo/bar/baz.png filter=lfs diff=lfs merge=lfs -text
foo/bar/* filter=lfs diff=lfs merge=lfs -text
*.png filter=lfs diff=lfs merge=lfs -text
You can share the LFS configuration with other members by git pushing the .gitattributes file:
$ git add .gitattributes
$ git commit -m "add git lfs attributes"
$ git push
Push files tracked by LFS to Backlog
If you have set up Git LFS in the previous section, when your git push contains a file tracked by LFS, it will be automatically uploaded as an LFS file.
$ git add example.png
$ git commit -m "add git lfs file"
$ git push
Note: If you use git clone, push, pull, etc, with SSH protocol, execute the following command first to explicitly set the LFS URL. This is not required for HTTPS protocol.
$ git config -f .lfsconfig lfs.url https://{SPACE_ID.DOMAIN}/git/{PROJECT_KEY}/{REPOSITORY_NAME}.git/info/lfs
Example:
$ git config -f .lfsconfig lfs.url https://foo.backlog.com/git/BAR/baz.git/info/lfs
The LFS base endpoint is added to the .lfsconfig file as follows:
[lfs]
url = https://foo.backlog.com/git/BAR/baz.git/info/lfs
You can git push the .lfsconfig file to share the LFS configuration with other members:
$ git add .lfsconfig
$ git commit -m "add git lfs config"
$ git push
Did you know?
The required username and password are the same as those entered during git clone or git push using the HTTPS protocol.Delete file patterns tracked by LFS
Use the following command to delete the tracking file pattern managed by LFS:
$ git lfs untrack "foo/bar/baz.png"
The target pattern is deleted from .gitattributes as follows:
foo/bar/* filter=lfs diff=lfs merge=lfs -text
*.png filter=lfs diff=lfs merge=lfs -text
You can share your LFS settings with other members by git pushing the .gitattributes file.
$ git add .gitattributes
$ git commit -m "update git lfs attributes"
$ git push
Browse files tracked by LFS on Backlog
Files tracked by LFS will be indicated when viewed at the repository’s Files tab on Backlog.
Example of image file:
Other files:
For non-binary files, click Original format to display the contents on the browser.
How to use the LFS file lock function
If files tracked by LFS are edited at the same time by different users, a conflict will occur. To resolve this, the file lock function allows a user to lock a file to prevent other users from updating it at the same time.
This section explains how to use the file lock function provided by LFS.
Add lockable flag for LFS-tracked files
The first step of using the file lock function is to add the “lockable” flag to the LFS file-matching patterns.
Did you know?
Git LFS automatically makes files flagged as “lockable” read-only on the local file system. Users will have read-only permission for the file. This is to prevent users from accidentally editing a file without locking it first.The following command sets all files under the foo/bar/ directory in the repository to be lockable.
$ git lfs track "foo/bar/*" --lockable
This will add the following line to the .gitattributes file:
foo/bar/* filter=lfs diff=lfs merge=lfs -text lockable
By adding lockable to the pattern in the.gitattributes file, files that match the target pattern can be locked. Remember to commit and push the changes so that your team members will have the info when they clone the repo:
$ git add .gitattributes
$ git commit -m "update git lfs attributes lockable"
$ git push
Lock a file
After adding the lockable flag for Git LFS-tracked files, the matching files will be changed to read-only permission.
In order to acquire write permission to edit a target file, you need to lock the file to stop others from editing it.
For example, by locking the foo/bar/example.png file with the following command, you will have write permission for the file and it can be edited.
$ git lfs lock foo/bar/example.png
Locked foo/bar/example.png
Get a list of locked files
You can list the locked files in the repository with the following command:
$ git lfs locks
foo/bar/example.png Jane ID:123
foo/bar/baz.png Mike ID:123
Unlock a file
If you do not need write permission for the target file, you can delete the lock by passing the file path or ID with the following command:
$ git lfs unlock foo/bar/example.png
$ git lfs unlock --id=123
You can also use the --force flag to force unlock another person’s locked file:
$ git lfs unlock foo/bar/baz.png --force