Troubleshooting Git LFS

— 10 minute read

Photo by USGS on Unsplash

Table of contents

About Git LFS

Git Large File Storage (LFS) is a Git extension for versioning large files, without those files taking up space in your repository.

Git Large File Storage (LFS) replaces large files such as audio samples, videos, datasets, and graphics with text pointers inside Git, while storing the file contents on a remote server like GitHub.com or GitHub Enterprise.

Git Large File Storage | GitHub

Once LFS is enabled, configured and tracking the files you want to store in your LFS service (rather than in your remote Git repository), those files will be represented in your remote repository with ‘pointer’ files, which look like this:

version https://git-lfs.github.com/spec/v1
oid sha256:561aaf45bdfaf2b18a51a11fb537f6cdf9b06baa40e9c33548d1f73ae8f87c6a
size 1259499

Download files from LFS

If a file has been added to the remote repository from another machine or by another developer / automated process, and you git pull to retrieve that file, but you see a pointer file in your local workspace instead of the contents of the file, you can pull down the actual file from your LFS service with the following command:

git lfs pull

Files missing from LFS: How to resolve

It’s possible to end up with large files in your remote repository that should have been stored in your LFS service. This can happen if you push files to your remote repository before Git LFS has been configured to track those files.

In my testing, editing my .gitattributes file directly didn’t retroactively include files that already existed in my remote repository, even after adding/committing that file and pushing my changes up to my remote repository.

The following steps resolved the issue for me.

Tidy up your .gitattributes file

Check your .gitattributes file and remove any lines that reference a ‘glob’ pattern that isn’t being applied to existing files in your remote repository.

Skip this step if you don’t have any matching ‘glob’ patterns for the files that are missing from your LFS service.

Track files with the LFS CLI

Use the git lfs CLI to add the required ‘glob’ patterns to your .gitattributes file - e.g.

git lfs track path/to/files/**/*.ext

After executing git lfs track, you should see the missing files referenced by the glob pattern(s) you specified show up in your list of ‘Unstaged Changes’ - either via git status or the relevant area of your favourite Git client.

Commit and push your changes

  1. Add/commit your unstaged changes:
    • Your .gitattributes file.
    • Any files referenced by glob patterns that you added with git lfs track.
  2. git push to your remote repository to upload those files to Git LFS.

What about previous versions of untracked files?

The process above won’t remove the content of LFS files from previous versions of those files in your remote repository (from previous commits) - it will only replace their contents with the LFS pointer information in the commit that you created above.

Fully removing the contents of large files that are tracked in LFS from your remote repository requires rewriting your Git history. This can be done with tools like BFG or git filter-repo.

Details of how to use those tools is beyond the scope of this post, but if you do consider using them, make sure to backup your repository beforehand as rewriting Git history is a destructive operation!

Resources