lfs Git Command Guide

Git LFS (Large File Storage) is a system for managing and versioning large files in association with a Git repository. Instead of storing large files within the Git repository as blobs, Git LFS stores special “pointer files” in the repository while storing the actual file contents on a Git LFS server.

Git LFS Architecture:

How Git LFS Works:

Pointer Files: Git repository stores small text files containing LFS object metadata
Clean Filter: Converts large files to pointer files when staging
Smudge Filter: Converts pointer files back to large files when checking out
LFS Server: Stores actual large file content separately from Git repository
Pre-push Hook: Uploads large file content to LFS server before Git push

Pointer File Format:

version https://git-lfs.github.com/spec/v1
oid sha256:abc123...
size 1048576

Git LFS Installation and Setup:

Basic Installation:

# Install Git LFS
curl -s https://packagecloud.io/install/repositories/github/git-lfs/script.deb.sh | sudo bash
sudo apt-get install git-lfs

# Or on macOS
brew install git-lfs

# Initialize in repository
cd my-repo
git lfs install

Repository Configuration:

# Track specific file types
git lfs track "*.psd"
git lfs track "*.zip"
git lfs track "assets/videos/*"

# Track files by size threshold
git lfs track --filename "*.mov" --size-threshold 100MB

# View tracked patterns
git lfs track

Remote Storage Configuration:

# Configure LFS server URL
git config lfs.url https://lfs-server.company.com/repo.git/info/lfs

# Use GitHub LFS (automatic)
git remote add origin https://github.com/user/repo.git

# Use GitLab LFS (automatic)
git remote add origin https://gitlab.com/user/repo.git

File Tracking and Management:

Track Large Files:

# Track specific file types
git lfs track "*.mp4" "*.mov" "*.zip"

# Track individual files
git lfs track "large-dataset.bin"

# Track by pattern
git lfs track "assets/**/*"

View Tracking Status:

# List tracked patterns
git lfs track

# Show tracked files in repository
git lfs ls-files

# Check LFS file status
git lfs status

Untrack Files:

# Stop tracking specific pattern
git lfs untrack "*.tmp"

# Untrack specific file
git lfs untrack "obsolete-file.dat"

# Migrate away from LFS
git lfs migrate export --include="*.mov"

Workflow Integration:

Standard Git Workflow with LFS:

# Initialize LFS in repository
git lfs install

# Track large file types
git lfs track "*.mov" "*.mp4" "*.zip"

# Add .gitattributes to repository
git add .gitattributes
git commit -m "Add LFS file tracking"

# Work with large files normally
git add large-video.mov
git commit -m "Add product demo video"

# Push normally (LFS handles large files)
git push origin main

Migration to LFS:

# Migrate existing large files to LFS
git lfs migrate import --include="*.mov,*.mp4"

# Or migrate specific files
git lfs migrate import --include-ref=HEAD --include="assets/videos/*"

# Push LFS objects
git push origin main

LFS-Specific Operations:

# Fetch LFS objects
git lfs fetch origin

# Pull with LFS objects
git lfs pull origin

# Check LFS object integrity
git lfs fsck

Advanced LFS Features:

Batch Operations:

# Process multiple LFS files
git lfs ls-files | xargs -I {} git lfs checkout {}

# Batch migrate files
find assets/ -name "*.mov" -exec git lfs track {} \;

# Bulk status check
git lfs status | grep -E "(modified|untracked|ignored)"

Lock and Collaboration:

# Lock file for exclusive editing
git lfs lock "critical-document.docx"

# Check lock status
git lfs locks

# Unlock when done
git lfs unlock "critical-document.docx"

# Force unlock (admin)
git lfs unlock --force "critical-document.docx"

Server Management:

# Prune old LFS objects
git lfs prune

# Deduplicate LFS storage
git lfs dedup

# Check LFS server connectivity
git lfs env

Configuration and Customization:

Global Configuration:

# Set default LFS settings
git config --global lfs.concurrenttransfers 8
git config --global lfs.basictransfersonly false
git config --global lfs.tustrictattributes false

# Configure transfer adapters
git config --global lfs.transfer.maxretries 5
git config --global lfs.transfer.maxretrydelay 10s

Repository-Specific Settings:

# Set LFS URL for this repository
git config lfs.url https://custom-lfs-server.com/repo.git/info/lfs

# Configure batch size
git config lfs.batchtransfer true
git config --add lfs.transfer.maxbatchsize 100

Environment Variables:

# Override LFS settings
export GIT_LFS_SKIP_SMUDGE=1  # Skip downloading LFS objects
export GIT_LFS_PROGRESS=1     # Show progress bars
export GIT_LFS_TRACE=1        # Enable debug tracing

Integration with CI/CD:

Automated LFS Setup:

#!/bin/bash
# CI/CD pipeline LFS setup

# Install Git LFS
curl -s https://packagecloud.io/install/repositories/github/git-lfs/script.deb.sh | bash
apt-get install -y git-lfs

# Initialize LFS
git lfs install

# Pull LFS objects
git lfs pull

# Verify LFS objects
git lfs fsck

# Run tests with LFS files
npm test

Build System Integration:

# Makefile with LFS awareness
assets: $(LFS_FILES)
  @echo "LFS files ready for build"

# Check LFS status in build
check-lfs:
  @if ! git lfs status | grep -q "Git LFS objects"; then \
    echo "No LFS objects found"; \
  fi

Troubleshooting Common Issues:

LFS Not Working:

# Check LFS installation
git lfs version

# Verify LFS initialization
git lfs env

# Check .gitattributes
cat .gitattributes | grep -i lfs

# Reinitialize if needed
git lfs install --force

Network and Authentication:

# Test LFS server connectivity
git lfs env | grep url

# Check authentication
git config lfs.url

# Debug transfer issues
GIT_LFS_TRACE=1 git lfs fetch 2>&1 | head -20

File Corruption Issues:

# Verify LFS object integrity
git lfs fsck

# Check specific object
git lfs fsck --objects abc123...

# Repair corrupted objects
git lfs prune --verify-remote

Performance Issues:

# Check transfer settings
git config lfs.concurrenttransfers

# Optimize for large files
git config lfs.transfer.maxretries 10
git config lfs.transfer.maxretrydelay 30s

# Monitor LFS operations
git lfs status --porcelain

Real-World Usage Examples:

Media Production Repository:

#!/bin/bash
# Setup for video production team

# Initialize LFS
git lfs install

# Track all media files
git lfs track "*.mov" "*.mp4" "*.wav" "*.aiff"
git lfs track "*.psd" "*.ai" "*.jpg" "*.png"
git lfs track "assets/**/*"

# Configure for large file handling
git config lfs.concurrenttransfers 16
git config lfs.transfer.maxbatchsize 50

# Add to repository
git add .gitattributes
git commit -m "Configure LFS for media files"

# Team workflow
echo "Media files now tracked with LFS - normal Git workflow applies"

Game Development Assets:

# Game asset management with LFS

# Track game assets
git lfs track "*.fbx" "*.obj" "*.dae"      # 3D models
git lfs track "*.png" "*.jpg" "*.tga"       # Textures
git lfs track "*.wav" "*.ogg" "*.mp3"       # Audio
git lfs track "*.unitypackage"              # Unity packages

# Configure for game development
git config lfs.url https://git-lfs.company.com/game-assets.git/info/lfs

# Asset pipeline integration
git lfs track "Assets/Textures/**/*"
git lfs track "Assets/Models/**/*"
git lfs track "Assets/Audio/**/*"

# Lock critical assets
git lfs lock "Assets/Levels/main-level.unity"

Scientific Data Repository:

# Large dataset management

# Track scientific data files
git lfs track "*.hdf5" "*.nc" "*.mat"       # Scientific data formats
git lfs track "*.csv" "*.xlsx"              # Data tables
git lfs track "datasets/**/*"               # Dataset directories

# Configure for large data transfers
git config lfs.concurrenttransfers 4
git config lfs.transfer.maxbatchsize 10
git config lfs.transfer.maxretrydelay 60s

# Data validation workflow
git lfs track "validation-scripts/*"
git add .gitattributes
git commit -m "Configure LFS for scientific datasets"

How does Git LFS improve repository performance?

LFS stores only pointer files in Git (typically <1KB each), dramatically reducing clone times and repository size while maintaining full file history.

What’s the difference between Git LFS and Git Annex?

Git LFS is simpler, focused on large files with centralized storage. Git Annex is more flexible, supports distributed storage, but has steeper learning curve.

Can Git LFS work with existing repositories?

Yes, can migrate existing large files to LFS using git lfs migrate import. Works with any Git repository, doesn’t require repository recreation.

How do LFS locks work for collaboration?

LFS locks prevent concurrent editing of binary files. When locked, other users can’t push changes to that file until lock is released.

What’s the impact of LFS on Git operations?

Most Git operations work normally. git clone/pull/fetch automatically handle LFS objects. Only storage location differs - LFS server vs Git repository.

Can LFS work without internet connection?

No, requires LFS server connectivity for downloading/uploading large file content. Pointer files work offline, but actual content requires network access.

How do I migrate from LFS back to regular Git?

Use git lfs migrate export to convert LFS files back to regular Git blobs. Requires LFS server access and may create very large repository.

What’s the relationship between LFS and Git submodules?

LFS manages individual large files; submodules manage entire repositories. Can use both together - LFS for large assets, submodules for component repositories.

How do I handle LFS in CI/CD pipelines?

Install Git LFS in pipeline, run git lfs pull to download objects, use git lfs status to verify. Configure LFS authentication for pipeline access.

Can LFS work with Git protocols other than HTTP?

Yes, works with HTTP/HTTPS, SSH, and Git protocols. LFS server endpoint configured separately from Git remote URL.

What’s the storage overhead of LFS pointer files?

Pointer files are very small (~100-200 bytes each), containing only metadata. Actual file content stored on LFS server, not in Git repository.

How do I handle LFS objects in Git hooks?

LFS objects available during hooks. Use git lfs status to check LFS file state. Pre-push hook automatically uploads new LFS objects.

Can LFS work with Git worktrees?

Yes, LFS works normally with worktrees. Each worktree can have different LFS object versions checked out as needed.

What’s the difference between LFS and Git’s large file handling?

Git has 2GB blob limit and stores all content in repository. LFS removes size limits and stores content externally while maintaining Git workflow.

How do I troubleshoot LFS authentication issues?

Check LFS URL configuration, verify credentials, test with curl against LFS endpoint, check for certificate issues, verify LFS server accessibility.

Can LFS work with GitHub/GitLab’s built-in LFS?

Yes, GitHub and GitLab provide LFS server functionality. No additional server setup required - just enable LFS and push normally.

How do I handle LFS objects in deployment?

Deploy scripts should run git lfs pull to ensure large files are available. Consider LFS object caching for faster deployments.

What’s the impact of LFS on repository size?

Dramatically reduces repository size by moving large file content to LFS server. Only pointer files remain in Git repository.

Can LFS work with shallow clones?

Yes, but shallow clones may not include LFS objects. Use git lfs fetch to get LFS objects for shallow repository, or avoid shallow clones with LFS.

How do I monitor LFS usage and costs?

Use git lfs ls-files to see tracked files, git lfs status for transfer status, LFS server analytics for storage usage and costs.

Applications of Git LFS

Media Production: Manage large video, audio, and image files in creative projects
Game Development: Handle large game assets, textures, models, and audio files
Scientific Computing: Store large datasets, simulation results, and research data
Enterprise Applications: Manage large binary assets, documents, and media files
Machine Learning: Version control large model files, datasets, and training data
Digital Asset Management: Organize and version control large media libraries and archives