Git struggles with large files because every time a file is updated, a new version is downloaded. This can cause Git processes (e.g., clone, push, pull) to take a long time. Git Large File Storage (LFS) is an extension created to solve these issues.
With Git LFS, large files are tracked and only downloaded when needed (during Git checkout). Less data is downloaded, so cloning/fetching from repositories is faster. Git LFS also stores the file’s metadata or pointer rather than the large file. By maintaining the repository within 1GB, Git LFS helps maintain Git performance.
In this guide, we’ll show you how to:
- Install LFS
- Add files
- Push files
- Delete file patterns
- Browse files
- Lock files
Install LFS
LFS is an extension for the Git command and needs to be downloaded and installed based on your operating system (Mac or Windows).
For Mac:
- Run brew update.
- Run brew install git-lfs.
- Run git lfs install.
For Windows:
- Download the installer for Windows.
- Run the installer for Windows.
- Run git lfs install.
Add files
To track files with LFS, set the target file pattern in each repository.
To add files to be tracked:
- Execute the command
$ git lfs track [<pattern>]
in the target repository. - Add files by matching them using a <pattern> as seen in these examples:
- Specifying a single file:
-
$ git lfs track "foo/bar/baz.png"
- Specifying all files in a single directory:
-
$ git lfs track "foo/bar/*"
- Specifying all files with a single extension:
-
$ git lfs track "*.png"
To display all tracked patterns that have been set, use the commands:
-
$ git lfs track
-
Listing tracked patterns
-
foo/bar/baz.png (.gitattributes)
-
foo/bar/* (.gitattributes)
-
*.png (.gitattributes)
The following 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
To share the LFS configuration with other members, use the commands:
-
$ git add .gitattributes
-
$ git commit -m "add git lfs attributes"
-
$ git push
Push files
The files added to your Git LFS will be automatically uploaded as an LFS file if they’re part of your Git push.
-
$ git add example.png
-
$ git commit -m "add git lfs file"
-
$ git push
If you use clone, push, pull, or similar commands with SSH protocol, execute the following command first to set the LFS URL.
-
$ git config -f .lfsconfig lfs.url https://{SPACE_ID.DOMAIN}/git/{PROJECT_KEY}/{REPOSITORY_NAME}.git/info/lfs
For 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
Good to know
The username and password are the same as with git clone or git push using HTTPS protocol.Delete file patterns
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
On the repository’s “Files” tab, files tracked by LFS are indicated with a banner message:
Other files show the following banner message:
For nonbinary files, select “Original format” to display the contents in the browser.
Lock files
The LFS file lock function prevents multiple users from updating a file at the same time.
To use the lock function, add the “lockable” flag to the LFS file-matching patterns. Files flagged as “lockable” are automatically made read-only to prevent users from 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
To edit a file, you need to lock it to get write permission and prevent others from editing it at the same time. For example, you can lock the file foo/bar/example.png with the following:
-
$ git lfs lock foo/bar/example.png
-
Locked foo/bar/example.png
To get a list of locked files, use the following command:
-
$ git lfs locks
-
foo/bar/example.png Jane ID:123
-
foo/bar/baz.png Mike ID:123
To unlock a file, pass 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 user’s locked file:
-
$ git lfs unlock foo/bar/baz.png --force