Git is not good at handling large files such as audio, video, and high-quality images. If you include such a large file in your Git repository, the git clone,git push, and git pull processes can take a long time.

Git LFS（Large File Storage, LFS) is a Git extension developed by GitHub, Microsoft, Atlassian, and other contributors solving the problems caused by large files. This makes it possible to handle large files more efficiently.

Download the large files that you need

For example, the files tracked by LFS will download only what is needed during git checkout, not during git clone or git pull.

Manage large files outside the Git repository

There is no actual file managed by LFS in the user's remote repository but, only the file's metadata is stored. Metadata is a text file of several hundred bytes that stores information for querying the LFS server for an entity.

This makes it easy to keep the Git repository within 1GB which is a general recommendation for maintaining Git performance.

Installing LFS

LFS is provided as an extension plug-in 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

Basics Usage of LFS

To track files with LFS, you need to set the target file pattern in each repository.

This section explains the basic usage of LFS.

Adding a file pattern to track files with LFS

Execute the following command in the target repository:

$ git lfs track [<pattern>]

You can match files tracked by LFS under the condition of <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 patterns set with the following 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 push this.gitattributes file:

$ git add .gitattributes
$ git commit -m "add git lfs attributes"
$ git push

Push files tracked by LFS to Backlog

you have completed the necessary settings in the previous section. If you git push the targeted file, 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.. with SSH protocol, execute the following command first to explicitly set the LFS URL. Not required for HTTP protocol:

$ git config -f .lfsconfig lfs.url https://{SPASE_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 this.lfsconfig file to share the LFS configuration with other members:

$ git add .lfsconfig
$ git commit -m "add git lfs config"
$ git push

❗️Note: The required username and password are the same as those entered when git clone orgit push with the HTTP protocol.

Browsing files tracked by LFS on Backlog

Files tracked by LFS can be viewed from the Backlog Git repository file screen.

Image file:

Other files:

For non-binary files, click “Original format” to display the contents on the browser.

Deleting file patterns tracked by LFS

Use the following command to delete the 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 push this .gitattributes file.

$ git add .gitattributes
$ git commit -m "update git lfs attributes"
$ git push

How to use the LFS file lock function

If the files tracked by LFS are edited at the same time, a conflict will occur. File lock function allows users to lock a file which prevents other users from updating at the same time.

This section explains how to use the file lock function by LFS.

Add a lockable file pattern

The first step using the file lock function is to define the file patterns that can be locked. 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. Git LFS automatically makes them read-only on the local file system.

Lock a file

In the previous section, we made files that match the target pattern read-only. This prevents users from accidentally editing the file without locking it.

You can acquire permission to edit the target file by locking the target file.

By locking the foo/bar/example.png file with the following command, the file will have write permission 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 to write permission for the target file, you can delete the lock by passing the path or ID to the following command:

$ git lfs unlock foo/bar/example.png
$ git lfs unlock --id=123

You can also use the --force flag to force an unlock to another person’s file:

$ git lfs unlock foo/bar/baz.png --force

Git LFS

About Git LFS