Introduction

Every developer hits the same wall eventually. You’ve got a repository full of images, videos, datasets — large binary files that Git wasn’t really built to handle. Your clone times stretch forever, your .git folder balloons to gigabytes, and every push feels like watching paint dry. It’s not that Git is broken; it’s just not the right tool for everything. Source code compresses beautifully and lives happily in Git. Large media files? They deserve better.

Git LFS fixes this by swapping those bulky files out for tiny pointer references that Git can manage effortlessly, while the actual content lives on a remote server. Your history stays clean, your clones stay fast, and you can finally version control those design files, game assets, and ML datasets without pulling your hair out. This guide walks through how LFS works, how to set it up, migrate existing repos, and use it reliably in production.

When to Use / When Not to Use

Use Git LFS when:

• Your repository contains files larger than 10MB
• You version binary assets (images, videos, audio, 3D models)
• You manage datasets or compiled artifacts
• Your clone/push times are dominated by large files
• You need to track specific file types across the repository

Avoid Git LFS when:

• All files are small text files (< 1MB)
• You can use external storage (S3, CDN) instead
• Your Git hosting doesn’t support LFS
• You need to search or diff file contents (LFS files are opaque blobs)
• You’re storing files that change frequently (LFS bandwidth costs add up)

Core Concepts

Git LFS works by replacing large files with pointer files:

flowchart TD
    A[Large File<br/>image.png 50MB] --> B[Git LFS Filter]
    B --> C[Pointer File<br/>128 bytes]
    C --> D[Git Repository<br/>Lightweight]
    B --> E[LFS Server<br/>Actual file stored]
    F[git clone] --> G[Download pointers]
    G --> H[Checkout triggers]
    H --> I[Download actual files<br/>from LFS server]
    I --> J[Working directory<br/>with real files]

Architecture and Flow Diagram

sequenceDiagram
    participant Dev as Developer
    participant Git as Git CLI
    participant LFS as Git LFS
    pointer as Pointer File
    participant LFSRemote as LFS Server
    participant GitRemote as Git Remote

    Dev->>Git: git add large-file.bin
    Git->>LFS: Smudge filter detects LFS file
    LFS->>LFS: Generate SHA256 hash
    LFS->>pointer: Create pointer file
    LFS->>LFSRemote: Upload actual file
    LFS->>Git: Stage pointer file
    Git->>GitRemote: Push pointer (small)
    Dev->>Git: git clone
    Git->>GitRemote: Download pointers
    Git->>LFS: Checkout triggers smudge
    LFS->>LFSRemote: Download actual files
    LFSRemote-->>LFS: Large file content
    LFS->>Dev: Working directory with real files

Step-by-Step Guide

1. Install Git LFS

# macOS
brew install git-lfs

# Ubuntu/Debian
sudo apt install git-lfs

# Windows
# Download from git-lfs.github.com

# Initialize (run once per user)
git lfs install

2. Verify LFS Installation

# Verify Git LFS is installed and working
git lfs version

# Check LFS filters are registered
git lfs install --force

# Verify LFS smudge/clean filters are active
git config --list | grep lfs

3. Configure LFS Tracking

Git LFS tracking works through Git’s smudge and clean filter infrastructure. When you tell LFS to track a file pattern, it registers these filters in .gitattributes — a file that Git reads to apply special handling to matching files. The clean filter intercepts files as they are staged, redirects the actual content to the LFS server, and replaces it with a lightweight pointer. The smudge filter does the reverse during checkout, downloading the real content and placing it in your working directory.

The tracking configuration lives in .gitattributes, which should always be committed to the repository. This is how every team member automatically gets the same LFS rules. Without .gitattributes in the repository, each developer would need to configure LFS tracking manually.

There are three common strategies for deciding what to track:

• By file extension — track all *.psd or *.png files so any file of that type automatically uses LFS.
• By directory path — useful when large files live in specific directories like datasets/ or models/ but other files with the same extension in different directories should stay in Git.
• By individual file — for case-by-case control when you have specific large files but don’t want to blanket-track an entire type.

Start with a conservative set of patterns and expand as needed. Tracking too many file types adds LFS overhead to files that may never be large, while tracking too few risks accidentally committing a big binary directly into Git history.

3.1 Set Up Tracking Patterns

Before tracking files, decide which patterns to use. Common strategies:

• Track by extension: *.psd, *.png, *.mp4
• Track by directory: datasets/*.csv, models/*.bin
• Track specific files: models/model-v1.bin

3.2 Track File Types

# Track specific file types
git lfs track "*.psd"
git lfs track "*.png"
git lfs track "*.mp4"
git lfs track "datasets/*.csv"

# Track specific large files
git lfs track "models/model-v1.bin"

# View tracked patterns
git lfs track

# This creates/updates .gitattributes
cat .gitattributes
# *.psd filter=lfs diff=lfs merge=lfs -text

3.3 Initialize Repository

# Initialize LFS in an existing repository
git lfs install

# Verify LFS is active
git lfs version

4. Commit and Push

# Commit the .gitattributes file (important!)
git add .gitattributes
git commit -m "chore: configure Git LFS tracking"

# Add large files normally
git add large-file.bin
git commit -m "feat: add large asset"

# Push (LFS files upload automatically)
git push origin main

5. Clone LFS Repository

# Standard clone (downloads LFS files)
git clone https://github.com/user/repo.git

# Clone without LFS files (faster)
git clone --filter=blob:none https://github.com/user/repo.git

# Pull LFS files later
git lfs pull

# Pull specific paths
git lfs pull --include="images/*"

6. Migration: Convert Existing Repository

# Install git-lfs-migrate
brew install git-lfs

# Migrate specific file types (rewrites history)
git lfs migrate import --include="*.psd,*.png,*.mp4" --everything

# Migrate with backup
git lfs migrate import --include="*.bin" --everything --verbose

# Push migrated history
git push --force --all
git push --force --tags

Warning: History rewriting requires force push and coordination with all collaborators.

7. LFS Management Commands

# List LFS files in repository
git lfs ls-files

# Show LFS file details
git lfs ls-files --long

# Check LFS status
git lfs status

# Prune old LFS objects
git lfs prune

# Fetch specific LFS objects
git lfs fetch --all

# Verify LFS integrity
git lfs fsck

Production Failure Scenarios

Scenario	Impact	Mitigation
LFS server unavailable	Can’t checkout files	Cache LFS files locally; use git lfs fetch --all
Bandwidth limits exceeded	Push/clone fails	Monitor usage; compress files; use external storage for archives
Pointer file committed without LFS	Large file in Git history	Use pre-commit hook to catch; migrate with git lfs migrate
LFS file corruption	Checkout fails	Run git lfs fsck; re-fetch from server
Migration breaks collaboration	Team confusion	Communicate migration; provide re-clone instructions
Storage limits reached	Can’t push new LFS files	Prune old objects; upgrade storage plan; archive unused files

Trade-off Analysis

Aspect	Git LFS	External Storage
Integration	Seamless with Git	Manual sync required
Versioning	Full Git history	Separate versioning
Cost	LFS storage fees	S3/CDN costs
Clone speed	Fast (on-demand download)	Manual download
Collaboration	Native Git workflow	Extra steps
Backup	Git + LFS server	Separate backup strategy

Implementation Snippets

Pre-commit hook to catch missing LFS tracking:

#!/bin/bash
# .husky/pre-commit
large_files=$(git diff --cached --name-only | while read file; do
  if [ -f "$file" ] && [ $(stat -f%z "$file" 2>/dev/null || stat -c%s "$file" 2>/dev/null) -gt 1048576 ]; then
    if ! git check-attr filter "$file" | grep -q "lfs"; then
      echo "$file"
    fi
  fi
done)

if [ -n "$large_files" ]; then
  echo "Error: Large files not tracked by LFS:"
  echo "$large_files"
  echo "Run: git lfs track '<pattern>'"
  exit 1
fi

LFS configuration for specific paths:

# .gitattributes
# Images
*.png filter=lfs diff=lfs merge=lfs -text
*.jpg filter=lfs diff=lfs merge=lfs -text
*.gif filter=lfs diff=lfs merge=lfs -text

# Design files
*.psd filter=lfs diff=lfs merge=lfs -text
*.ai filter=lfs diff=lfs merge=lfs -text
*.sketch filter=lfs diff=lfs merge=lfs -text

# Media
*.mp4 filter=lfs diff=lfs merge=lfs -text
*.mp3 filter=lfs diff=lfs merge=lfs -text

# Datasets
*.csv filter=lfs diff=lfs merge=lfs -text
*.parquet filter=lfs diff=lfs merge=lfs -text

# Binaries
*.bin filter=lfs diff=lfs merge=lfs -text
*.exe filter=lfs diff=lfs merge=lfs -text
*.dll filter=lfs diff=lfs merge=lfs -text

CI configuration with LFS:

# GitHub Actions
- uses: actions/checkout@v4
  with:
    lfs: true # Automatically pulls LFS files

# Or manual LFS pull
- uses: actions/checkout@v4
- run: git lfs pull

Observability Checklist

• Logs: Log LFS upload/download operations and failures
• Metrics: Track LFS storage usage, bandwidth, and file counts
• Alerts: Alert on storage limits, bandwidth thresholds, and fetch failures
• Dashboards: Monitor LFS adoption and repository size trends
• Traces: Trace LFS file lifecycle from add to checkout

Security & Compliance Considerations

• LFS files are stored on remote servers; verify encryption at rest
• Access controls apply to LFS objects; configure repository permissions
• For regulated data, ensure LFS provider meets compliance requirements
• LFS pointer files don’t contain file contents; safe to commit publicly
• Audit LFS access logs for unauthorized downloads
• Consider encrypting sensitive LFS files before committing

Common Pitfalls / Anti-Patterns

Anti-Pattern	Why It’s Bad	Fix
Forgetting to commit .gitattributes	LFS not configured for team	Always commit .gitattributes with tracking changes
Tracking too many file types	Unnecessary LFS overhead	Track only files > 1MB
Not pruning old LFS objects	Disk space waste	Run git lfs prune regularly
LFS files in submodule	Complex LFS handling	Keep LFS files in main repository
Migrating without team coordination	Broken clones for collaborators	Communicate migration; provide re-clone steps
Using LFS for frequently changing files	High bandwidth costs	Use external storage for volatile large files

Quick Recap Checklist

• Install Git LFS and run git lfs install
• Configure file type tracking in .gitattributes
• Commit .gitattributes before adding large files
• Set up pre-commit hooks to catch missing LFS tracking
• Configure CI to pull LFS files automatically
• Monitor LFS storage usage and bandwidth
• Set up regular pruning schedule
• Document LFS workflow for team members

Extended Production Failure Scenarios

LFS Quota Exceeded

Git hosting providers cap your LFS storage. GitHub’s free tier is 1GB, GitLab gives you 10GB, Bitbucket has 5GB. Hit that limit and the LFS server rejects uploads with batch response: Storage quota exceeded.

The catch: your Git commit succeeds anyway. Git only stores pointer files, so the commit goes through. The LFS push fails. You now have commits pointing to objects that were never uploaded. Anyone cloning after that gets pointer text instead of actual files.

Recovery is messy. You can’t just push again because the commits reference missing objects. Either free up storage by pruning old objects, upgrade your plan, or remove the bad commits and push replacements with smaller files.

Don’t let it get that far. Watch your LFS usage through your provider’s dashboard. Set alerts at 70-80% capacity. Before large pushes, check available space with git lfs status. For archival files you barely touch, store them on S3 or GCS instead of burning LFS quota on things you rarely need.

Pointer Files Without Actual Content

This failure mode catches every team at least once. A developer decides to track a new file type — say, .fbx for 3D models — and updates .gitattributes with *.fbx filter=lfs. They commit the attribute change, add the files, and push. What they forgot: they never ran git lfs install on their machine. The smudge and clean filters never registered, so Git stored the actual binary content as a plain Git blob, not an LFS pointer.

The consequences unfold in stages. First, the repository swells by whatever size those files are. Every clone pulls those bytes, even though the files should have been pointers. Second, other developers on the team pull the same commits and see .fbx files in their working directory — but when they run git lfs ls-files, nothing shows up. The files exist in Git but not in LFS. Third, if anyone tries git lfs pull expecting the files to materialize, nothing happens because the LFS server has no objects to serve. The files are trapped as regular Git blobs, invisible to LFS tooling.

The core problem is that Git commits succeed independently of LFS operations. Git only sees the pointer file content — if the filter never ran, Git never knew LFS was involved. The commit pointer references an object ID that exists in the Git object store, not in the LFS server. So even though the push to the Git remote succeeds, the LFS push never attempted to upload anything because there was nothing to upload.

Mitigation:

• Run git lfs install in a pre-commit hook or as part of developer onboarding so the filters are always registered before anyone can commit large files
• Use a CI check that runs git lfs ls-files and compares the output against actual file sizes — any tracked file over 1MB that doesn’t appear in LFS output fails the build
• If you discover files that slipped through, repair them with git lfs migrate import --include="*.fbx" --everything which rewrites history to replace the raw blobs with LFS pointers, then force push to update all branches

Extended Trade-offs

Aspect	Git LFS	Git Annex	External Storage (S3)
Cost	Provider-dependent (often paid after free tier)	Free — self-hosted	Pay-per-use, can be cheaper at scale
Accessibility	Native Git workflow	Complex — separate toolchain	Manual — separate download step
Versioning	Full Git history of pointers	Full history tracking	Separate versioning system needed
Setup	Simple — git lfs track	Complex — init, configure remotes	Moderate — SDK or CLI integration
Collaboration	Seamless — works with any Git host	Requires all users to install git-annex	Requires separate access management
Best for	Game assets, design files, ML datasets	Academic archives, personal backups	Static assets, distribution files

Security and Compliance: LFS Object Access Control

• Access control: LFS objects inherit repository permissions. If a user can clone the repo, they can download all LFS objects. For sensitive binaries, use private repositories with strict access controls.
• Bandwidth costs: LFS bandwidth is often billed separately from storage. Large teams cloning frequently can incur significant costs. Use git clone --filter=blob:none to skip LFS downloads until needed.
• Regional storage: Some LFS providers store objects in specific regions. For compliance (GDPR, data residency), verify where LFS objects are stored. GitHub LFS uses the same region as the repository; self-hosted GitLab allows region configuration.
• Encryption: LFS objects are encrypted in transit (HTTPS) but may not be encrypted at rest depending on the provider. For sensitive binaries, encrypt files before adding them to LFS and manage decryption keys separately.
• Audit logging: Track LFS download events for compliance. Most providers log LFS access separately from Git access. Review logs periodically for unusual download patterns.

Cross-Roadmap References

• Object Storage — System Design roadmap: S3-compatible blob storage for large binary assets
• System Design Learning Roadmap — Broader architecture context for large file handling

Interview Questions

Further Reading

• Git LFS Official Site
• Git LFS Documentation
• GitHub LFS Documentation
• GitLab LFS Documentation
• LFS Migration Guide
• Git LFS File Locking

Conclusion

Git LFS solves the fundamental tension between Git’s text-first design and the need to version large binaries. By replacing heavy files with lightweight pointers, LFS keeps clone times fast and repository sizes manageable while still tracking every version of your assets.