Intro and Requirements


What is Git LFS and how does it work?

Git LFS (Legendary Fabled Squid Large File Storage) is an extension of Git. The main purpose is to be able to more efficiently store large binary files. Git LFS allows the user to track certain files directly or by extension. After the files are tracked, Git LFS manages the files as Git normally would, while Git just maintains a text file with metadata about the binary file.

In GitKraken, when viewing the diff of a tracked LFS files, you will see a versioned URL, a generated sha, and a size pertaining to the size of the original contents of the file. An example could look like this:

Git LFS stores the actual content of the binary file in a special storage location, either on a custom server or via GitHub, GitLab, or BitBucket’s built in LFS storage. To see where the binary content is stored on your local machine, look in your repository’s .git/lfs/objects folder.

Git LFS uses a special Git Hook to handle pushing your LFS files to the special LFS location. It is important that Git Hooks are able to run on your machine when using Git LFS. To handle diffing and proper storage, LFS uses Git filters.

When you pull or checkout a new branch, all files are run through what is called a smudge filter. The smudge filter handles the necessary work required to properly put a file into your working directory. What LFS does is it reads the sha stored in Git, then uses that to find the appropriate binary file in the .git/lfs/objects folder. If it does not find the file it needs, it attempts to download the file from the LFS server found in the local repository’s git config file. Once the proper file is found or downloaded, Git LFS replaces the text sha with the actual binary file in your working directory.

When changes have been made to an LFS file and you wish to commit those changes, LFS uses the Git clean filter. The clean filter is run when a file is staged. This filter will read the binary content from the file and convert it to a sha, which will then be stored in Git while the original binary content will be stored in the .git/lfs/objects folder.

If you wish to learn more about how Git LFS works with Git, visit the GitHub repository to find the documentation.


Git LFS Requirements

In order to see the LFS option in the toolbar, you will need to have the following installed on your machine:

  • Git version 1.8.5 and up
  • LFS version 2.0.1 and up

Verify Git and LFS Versions

To verify that you have the proper version of Git installed on your machine, open a terminal or CMD and type the following:

git --version

You should see something like this:

git version 2.13.0

On windows you may see some extra characters appended to the version, that is fine. If you see anything other than a git version message, or an error, you will need to install git on your machine.

GitKraken requires at least version 1.8.5 to run LFS. If you have a version lower than 1.8.5 you will need to upgrade. To install or upgrade git on your machine, visit the git-scm website. The latest version of Git is recommended for the best overall experience.

To check if you have Git LFS installed and what version, we are going to run a similar command to that of Git in the terminal or CMD:

git lfs version

You should get output similar to the following:

git-lfs/2.1.0 (GitHub; windows 386; go 1.8.1; git bd2c9987)

If you do not have Git LFS installed or you have a version less than 2.0.0 installed, visit the LFS website to install the proper version.

Once both Git and Git LFS are installed, verify that they are on your path either by running the commands above or by checking your path in the terminal.

Note: Sometimes even after verifying that Git and Git LFS are on your path GitKraken will still not be able to find either application. This could be because the terminal or CMD is using a different path than the system or user path. For example, on macOS applications launched from the GUI have a different path than those launched from the terminal.

On macOS and Linux, you can run the following command to see the location of Git LFS on the path:

which git-lfs

and this command to see the location of Git on the path:

which git

On Windows, use:

where git-lfs

and:

where git