How to use Git Large File Storage (LFS) in Backlog

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:

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
0 people think that it is helpful. Was this helpful for you?

Have a question we didn't answer?

Contact support