Skip to main content

Git LFS notes

Git LFS (Large File Storage) is a great tool that stores binary files as pointers instead of actual files to save on storage and bandwith in your Git repos.

When you stage and commit a file with Git LFS installed and marked for tracking, Git LFS picks up the file and starts tracking it. When Git LFS is not installed obviously Git will do the tracking automatically. The problem arises when these 2 titans clash and that is a painful thing to deal with. This can happen simply by one person not installing Git LFS on their local environment and the 💩🌪️ happens.

I feel there is one golden rule every team should follow the moment they decide to use Git LFS : Devs must have Git LFS installed as soon as they get access to the repo. Based on my experience on large projects (monorepo with 4-5 teams and 30+ devs) it is enough for one person to accidentally track a file with Git which would normally be tracked by LFS and the whole team will suffer until someone sorts the mess out.

| If you’re looking for some useful git commands for everyday dev work check out my Git notes.

If you’re here I assume you’re dealing with some Git LFS pain and I hope my notes will help you.

Basic Git LFS commands (normal operation, no drama)

Use these commands for standard operation with Git LFS.

Install Gif LFS and pull the remote LFS pointers

git lfs install && git lfs pull

Remove Git LFS and reset local branch

I find the following command super useful when Git LFS finds untracked files that need removing from Git (uninstalling Git LFS allows us to reset the branch).

git lfs uninstall && git reset --hard HEAD

List tracked files

Use this to verify which files are tracked by Git LFS:

git lfs ls-files

List deleted files

This one allows us to see files that were tracked by Gif LFS even if they were deleted at some point:

git lfs ls-files --deleted

Git LFS - Move already tracked files from git to LFS (such drama)

When Git ends up tracking a file that usually would be tracked by Git LGS devs will see files popping up out of nowhere, and they will soon find other strange things happening, such as:

  • Random files appear out of nowhere and git reset --hard HEAD doesn’t remove them
  • Git LFS starts nagging about the untracked files
  • No Git LFS command (uninstall, pull, migrate, import) helps

What a pain… But worry not just follow these steps:

1. Remove the file from Git

  git rm --cached my-file.png

2. Track file (let LFS catch it)

  git add my-file.png

3. Commit the changes

  git commit -m "Add file to LFS"

4. Verify my-file is bein tracked as a pointer by Git LFS

  git lfs ls-files

5. Push the new LFS pointers to remote

  git lfs push origin my-branch

6. Push your branch

  git push -u origin my-branch

7. Merge your changes into main

8. Pull changes

You either need to pull changes into feature branches or update your local main branch or both…

  git pull origin main

9. Tell Git LFS it’s all fine

Git LFS will still freak out about the new file showing but instead of trying to track it we need to reset Git - for that we need to disable Git LFS temporarily:

  git lfs uninstall && git reset --hard HEAD

10. Reinstate Git LFS

The final but very important step is to re-activate Git LFS (you definitely don’t want to deal with this problem again):

  git lfs install && git lfs pull

Easy peasy. Enjoy!

Resources