📦 Git LFS Large File Management

Why LFS?

Git excels at managing text files (code, configuration), but it's not suited for large binary files (videos, design files, datasets, model weights). This is because Git stores the complete file for each version — a 100MB PSD modified 10 times takes up 1GB.

Git LFS (Large File Storage) replaces large files with a "pointer file," with the actual content stored on an LFS server. When cloning, it only downloads the version you need, not the entire history.

Installation and Setup

# Install LFS
git lfs install

# Tell LFS which files to manage (run in repository root)
git lfs track "*.psd"
git lfs track "*.zip"
git lfs track "*.mp4"
git lfs track "*.bin"
git lfs track "assets/models/*"

# This creates/updates the .gitattributes file
cat .gitattributes
*.psd filter=lfs diff=lfs merge=lfs -text
*.zip filter=lfs diff=lfs merge=lfs -text
*.mp4 filter=lfs diff=lfs merge=lfs -text
assets/models/* filter=lfs diff=lfs merge=lfs -text

# Commit .gitattributes
git add .gitattributes
git commit -m "chore: configure Git LFS"

Daily Usage

# View files managed by LFS
git lfs ls-files
5d2a0cbf9e - design-v3.psd
8f94173c2a - video-demo.mp4
a1b2c3d4e5 - models/weights.bin

# View actual size of LFS files (not pointer size)
git lfs ls-files --size

# Clone a repository with LFS files (automatically downloads LFS files)
git clone https://github.com/user/repo.git
# If LFS files aren't downloaded automatically:
git lfs pull

# Push LFS files
git add design.psd
git commit -m "feat: add design mockup"
git push origin main
# LFS files are automatically uploaded to the LFS server

# Update LFS files after switching branches
git checkout main
git lfs pull

Migrating an Existing Repository to LFS

# Migrate committed large files to LFS (rewrites history! requires force push)
git lfs migrate import --include="*.psd,*.zip,*.mp4" --everything

# ⚠️ This rewrites all commits containing these files
# Team members need to re-clone the repository

# Safer approach: only migrate future files, leave history untouched
git lfs track "*.psd"
git add .gitattributes
git commit -m "chore: track PSD files with LFS from now on"
# Historical PSDs still take up space, but new files go through LFS

⚠️ Warning: Important notes:

• LFS has free tier limits (GitHub: 1GB storage + 1GB/month bandwidth), exceeding requires payment
• Don't track text files (.js/.py/.json) — LFS reduces diff readability
• All team members must install git lfs, otherwise large files will appear as pointer files
• .gitattributes must be committed to the repository