home Explore Documentation & Help
Register Sign In

Navigation

Getting Started

User Guide

Team Collaboration

Advanced

FAQ & Help

Git LFS (Large File Storage)

What is Git LFS?

Git LFS (Large File Storage) is a Git extension for versioning large files like images, videos, datasets, and binaries. Instead of storing these files directly in Git, LFS stores pointers in the repository and the actual files on a remote server.

Installing Git LFS

Windows

winget install GitLFS

Or download from git-lfs.github.com

macOS

brew install git-lfs

Linux

sudo apt-get install git-lfs

Initialize

git lfs install

Using Git LFS with gityar

Track File Types

Tell Git which files to track with LFS:

# Track all PSD files
git lfs track "*.psd"

# Track all MP4 files
git lfs track "*.mp4"

# Track all files in a directory
git lfs track "assets/*"

# Track specific large file
git lfs track "dataset.csv"

This creates or updates .gitattributes file:

*.psd filter=lfs diff=lfs merge=lfs -text
*.mp4 filter=lfs diff=lfs merge=lfs -text

Commit and Push

# Add .gitattributes
git add .gitattributes

# Add your large files
git add large-file.psd

# Commit
git commit -m "Add large file with LFS"

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

Managing LFS Files

List Tracked Files

git lfs track

List LFS Files in Repository

git lfs ls-files

View LFS Status

git lfs status

Pull LFS Files

# Pull all LFS files
git lfs pull

# Pull specific branch
git lfs pull origin feature-branch

Fetch LFS Files

git lfs fetch --all

LFS Settings in gityar

Enable LFS

LFS is enabled by default in gityar. To verify:

  1. Go to repository Settings
  2. Check "Enable Git LFS" is checked

LFS Storage

LFS files are stored in:

data/lfs/

Storage Limits

Configure storage limits in app.ini:

[repository.upload]
LFS_MAX_FILE_SIZE = 104857600  # 100MB
LFS_MAX_STORAGE = 10737418240  # 10GB per repository

Migrating to LFS

Convert Existing Files to LFS

Use git lfs migrate:

# Migrate all PSD files
git lfs migrate import --include="*.psd"

# Migrate multiple file types
git lfs migrate import --include="*.psd,*.mp4,*.zip"

# Migrate and rewrite history
git lfs migrate import --include="*.psd" --everything

⚠️ Warning: Rewriting history changes commit hashes!

Push After Migration

git push --force

Best Practices

When to Use LFS

  • ✅ Files larger than 50MB
  • ✅ Binary files (images, videos, audio)
  • ✅ Datasets and archives
  • ✅ Compiled binaries
  • ✅ Design files (PSD, AI, Sketch)

When NOT to Use LFS

  • ❌ Source code files
  • ❌ Configuration files
  • ❌ Documentation
  • ❌ Small text files
  • ❌ Files that need diffing

General Tips

  • Track file extensions, not individual files
  • Keep .gitattributes updated
  • Monitor LFS storage usage
  • Clean up unused LFS files periodically
  • Document LFS usage for your team

Troubleshooting

Common Issues

"LFS objects not found":

git lfs fetch --all
git lfs checkout

"Insufficient disk space":

  • Clean LFS cache: git lfs prune
  • Increase storage limits
  • Remove unnecessary LFS files

"Authentication failed":

  • Verify credentials
  • Check LFS endpoint URL
  • Ensure LFS is enabled

Slow clone/pull:

  • Use shallow clone: git clone --depth 1
  • Skip LFS: GIT_LFS_SKIP_SMUDGE=1 git clone
  • Pull LFS later: git lfs pull

Check LFS Pointers

If files show as pointers instead of actual content:

# Download LFS files
git lfs pull

# Verify file
git lfs fsck

Clean LFS Cache

Remove old LFS objects:

# Preview what will be deleted
git lfs prune --dry-run

# Delete old objects
git lfs prune

LFS Commands Reference

Command Description
git lfs install Initialize LFS
git lfs track Track file patterns
git lfs ls-files List LFS files
git lfs status Show LFS status
git lfs pull Download LFS files
git lfs fetch Fetch LFS objects
git lfs push Push LFS objects
git lfs prune Clean old objects
git lfs migrate Migrate files to LFS
git lfs fsck Verify LFS objects

Next Steps