What is Git LFS and how does it work?
Git LFS (Legendary Fabled Squid Large File Storage) is a Git extension for storing large binary files.
Git LFS allows the user to track binary 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.
When viewing the diff of tracked LFS files in GitKraken Desktop, you will see a versioned URL, a generated SHA, and a size pertaining to the size of the original contents of the file:
Git LFS stores the binary file content on a custom server or via GitHub, GitLab, or BitBucket’s built-in LFS storage. To find the binary content’s location, 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. Because LFS uses Git filters for handling diffs and proper storage, make sure Git Hooks can run on your machine.
When pulling or checking out a new branch, all files run through a smudge filter. The smudge filter puts a file into your working directory.
LFS 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 SSH-agent with the binary file in your working directory.
LFS uses the Git clean filter for changes ready for commit and runs when a file is staged. This filter reads the binary content from the file and converts 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 documentation.
Git LFS Requirements
To enable LFS in GitKraken Desktop, you must first install Git and LFS. The minimum requirements are:
- Git version 2.39.3+
- LFS version 3.0.0+
- GitKraken Desktop version 7.0.0+
Note: Usually GitKraken Desktopdoes not require Git CLI to perform its operations. However, since we do utilize Git CLI to interact with LFS files you will need to have Git installed on your machine if you plan to use LFS.
Verify Git and LFS Versions
To verify whether you have the proper version of Git installed, open a terminal or CMD and type the following:
git --versionYou should see something like this:
git version 2.13.0On Windows you may see some extra characters appended to the version which is expected. If an error appears, please install (or upgrade) Git on your machine.
GitKraken Desktop requires version 2.3+ to run LFS. To install or upgrade Git on your machine, visit the git-scm website.
Run the following command in terminal or CMD to verify your machine’s version of Git LFS:
git lfs versionYou 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 Git LFS website to install the proper version.
After 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: If GitKraken Desktop still cannot find Git or Git LFS, the terminal or CMD may be using a different path than the system or user path. For example, on OSX applications launched from the GUI have a different path than those launched from the terminal.
On OSX and Linux, you can run the following command to see the location of Git LFS on the path:
which git-lfsand this command to see the location of Git on the path:
which gitOn Windows Command prompt, use:
where git-lfsand:
where gitOn Windows you can add to your Path Environmental Variable with the following method:
Search Env in the start menu.
Next navigate to Environmental Variables... Double click Path Click New to add the paths.
You will likely need to add both git and git LFS (LFS can have multiple paths, you would want to add them all).
Initializing LFS on an existing repo
Navigate to your Preferences and you should see the LFS tab in the left panel:
Note: If you do not see the LFS tab, make sure you have a GitKraken Desktop v3.0.0+ installed and you meet these System Requirements.
Click to initialize LFS on the repo:
Exit preferences to access two new things: an LFS button in the toolbar and an unstaged change to the .gitattributes file that needs to be committed.
Stage and commit the changes to the .gitattributes file to finish the LFS initialization.
Existing files need to be untracked from Git and re-tracked to count as LFS files. Consider removing the files from the repository (Git will think they have been removed/deleted), commit, then re-add the files and re-commit.
The re-added files should now follow your new LFS tracking pattern.
Initializing LFS on a new repo
When you initialize a new repository, you will have the option to Initialize with LFS.
Configuring LFS
Once LFS is initialized on a repository, add tracking patterns to the .gitattributes file. These tracking patterns will tell LFS which files to monitor in your repository.
Access the .gitattributes file by going to Preferences > LFS or by editing the .gitattributes file directly in your text editor.
As another option, add tracking patterns to the repository’s .gitattributes file through the Unstage pane in the right panel.
Select the WIP node, right click the file you wish to be tracked by LFS, and select the desired option under LFS.
Note: GitKraken Desktop will automatically perform an LFS pull after cloning a repo or initializing a submodule with LFS
When a file matches a pattern that is being tracked by LFS, an LFS tag appears next to the file name in the right panel.
Clicking on the file shows the LFS reference information:
Staging and committing LFS tracked files results in the reference files being saved to your local repo and the actual files being saved to your local LFS cache.
Once your repo is pushed to an LFS-capable remote, the reference files will be saved to the remote repo and the actual files will be pushed to your specified LFS server.
Most LFS actions, such as Checkout, Fetch, Pull, and Push will happen automatically as you use the standard commands in GitKraken Desktop. However, if you want to use an LFS command in isolation, use the LFS toolbar menu:
Click the arrow on the button and select the desired command. Other than Prune, all of the commands are run by GitKraken Desktop via the traditional operations.
Note: Pruning is not automatic. Pruning is considered a destructive operation, so be careful about when you run the Prune command. See the Git LFS documentation to learn more.
LFS FAQ
I updated to v3.0.0 of GitKraken Desktop but I cannot find LFS anywhere?
You will need to make sure you have Git v1.8.5 and LFS v2.0.0 installed on your local machine.
I switched repos and now I do not see the LFS button. Where did it go?
It is most likely that you have switched to a repository that does not have LFS initialized. If you wish to initialize this repo with LFS, you can do so by navigating to the hamburger menu → LFS → Initialize LFS on this repo.
I added a LFS tracking pattern in GitKraken Desktop but files with that pattern are not being tracked by LFS, what gives?
Only new files will be tracked by the newly added pattern. If files of the newly added pattern are already being tracked by Git, you will need to untrack them and then re-track them.
The easiest way to do this in GitKraken Desktop is to remove the files from the repository (Git will think they have been removed/deleted), commit, then re-add the files and re-commit. The re-added files should now follow your new tracking pattern.
After trying to push my files, I see a prompt requiring my credentials. What credentials is it referring to?
This prompt occurs if your LFS server credentials are not cached. If you are using the same remote hosting service (such as GitHub), then enter the hosting service credentials.
If you are using an internal LFS server (or another LFS service), you will need to enter the credentials for the LFS server.
Common Pitfalls
Why is LFS STILL not showing up?
If LFS is still not appearing as an option in GitKraken Desktop preferences menu, you may need to add it to your Path variable. This can happen if git or git LFS is not installed in the default directory. You should Verify Git and LFS Versions.
SSH Keys in GitKraken Desktop and the CLI
Unlike most features in GitKraken Desktop, the LFS feature does require git for the CLI as well as LFS. This means that if you are trying to use SSH, your key will need to be configured in your GitKraken Desktop and for the CLI.
You can automatically generate an SSH Key in GitKraken Desktop in Preferences > SSH and save wherever you want locally, or the key will be in your ~\.gitkraken\profiles folder if you generate from a specific integration.
You can also use the SSH Agent option to setup and manage your keys, and then tell GitKraken Desktop to use your agent. Adding an SSH Key to an SSH Agent by GitHub
Using LFS installed using Homebrew on macOS
If LFS was installed using Homebrew, it may not appear in your path. You can run sudo launchctl config user path "/opt/homebrew/bin:$PATH" to add homebrew utilities to the PATH for GUI apps. You can see more information on this from the Homebrew documentation.
