What is Git LFS?
Git LFS (Large File Storage) is an extension for Git that helps manage large files (like videos, images, datasets, or binaries) efficiently.
Instead of storing these big files directly in your repository, Git LFS stores a small pointer file in the repo. The actual content is stored on a separate LFS server.
This keeps your repository fast and small, even if it uses very large files.
When someone clones or pulls the repository, Git LFS automatically fetches the real content based on those pointers.
For related info about file handling, see the .gitattributes guide.
When to Use Git LFS
- When you need to version large files (media, datasets, binary assets).
- When your repository exceeds standard Git file size limits.
- When you want to keep your repository lightweight and fast.
Install Git LFS
- Download and install Git LFS from git-lfs.github.com.
- Initialize Git LFS in your repo:
git lfs install
Track Files with Git LFS
Tell Git LFS which file types to manage by using the track command.
For example, to track all Photoshop files:
git lfs track "*.psd"
Examples:
git lfs track "*.zip"
git lfs track "data/*.csv"
git lfs track "images/*.{png,jpg}"
How Git LFS Works
When you track a file type, Git adds a rule to your .gitattributes file, like:
*.psd filter=lfs diff=lfs merge=lfs -text
- When you add & commit a tracked file, Git stores a small pointer file.
- The actual large file is uploaded separately to the LFS server.
- When you clone or pull, Git LFS downloads the real content automatically.
Working with LFS Files
Add and commit LFS files as usual:
git add largefile.psd
git commit -m "Add large file"
git push origin main
The repository holds only the pointer file; the actual content stays on the LFS server.
Check Which Files Are Managed by LFS
git lfs ls-files
Untrack or Remove Files from LFS
- Edit .gitattributes and remove or change the related line.
- Run:
git lfs untrack "*.psd"
git add .gitattributes
git commit -m "Stop tracking PSD files with LFS"
Note: Existing file versions remain stored in LFS.
Tips & Best Practices
- Use Git LFS only for files that are too large or change too often.
- Confirm your hosting service supports LFS (especially private repos).
- Monitor your LFS storage and bandwidth limits; free plans often have quotas.
Troubleshooting
- If you clone a repo and see pointer text instead of real files:
git lfs pull
- If your remote doesn’t support LFS, you’ll get a push error.
- If you exceed your LFS storage or bandwidth, new files may fail to upload.
