Git LFS: Managing Large Files in Git Repositories

In this tutorial, you'll learn about Git LFS: Managing Large Files in Git Repositories. We cover key concepts, practical examples, and best practices.

Git LFS replaces large files with small pointer files and stores actual content on a remote server, keeping your repository small and cloning fast.

In this tutorial, you'll learn Git Large File Storage (LFS) for managing binary files, assets, and datasets in Git repositories. Standard Git stores every version of every file in history, making it inefficient for large files. LFS replaces large files with text pointers and stores the actual content on a remote server. By the end, you'll set up LFS, migrate existing repositories, and manage bandwidth limits.

flowchart LR
  A[Large file added] --> B[Git LFS intercepts]
  B --> C[Pointer file committed to Git]
  B --> D[Actual file uploaded to LFS store]
  C --> E[git push]
  E --> F[GitHub/GitLab]
  D --> F
  F --> G[git clone]
  G --> H[Pointer file downloaded]
  H --> I[Git LFS downloads actual file]

Installing Git LFS

# Install LFS
sudo apt install git-lfs
# or brew install git-lfs

# Initialize LFS (one-time per user)
git lfs install

# Verify installation
git lfs version

Expected output:

git-lfs/3.4.0 (GitHub; linux amd64; go 1.21)

Setting Up LFS in a Repository

cd your-repo
git lfs track "*.psd"
git lfs track "*.zip"
git lfs track "*.mp4"
git lfs track "assets/**"

Expected output after tracking:

Tracking "*.psd"
Tracking "*.zip"
Tracking "*.mp4"
Tracking "assets/**"

This creates a .gitattributes file:

*.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/** filter=lfs diff=lfs merge=lfs -text

Migrating Existing Files to LFS

If you already have large files committed without LFS, migrate them:

git lfs migrate import --include="*.psd,*.zip" --everything

Expected output:

migrate: Sorting commits: done, 50 commits
migrate: Rewriting commits: 100% (50/50), done
migrate: Updating refs: done

This rewrites history to move the matching files to LFS. Warning: This changes commit hashes and requires force-pushing.

Working with LFS Files

LFS files behave like normal files in your working directory:

# Add large files normally
echo "binary content" > large-file.zip
git add large-file.zip
git commit -m "Add large file"
git push

During clone or pull:

git clone repo-url
# LFS files are downloaded automatically

Or fetch LFS files later:

git lfs pull

LFS File Locking

LFS supports file locking to prevent merge conflicts on binary files:

# Lock a file
git lfs lock assets/logo.psd

# List locks
git lfs locks

# Unlock a file
git lfs unlock assets/logo.psd

# Unlock another user's file (if allowed)
git lfs unlock --force assets/logo.psd

File locking ensures that only one person edits a binary file at a time, preventing unresolvable merge conflicts.

LFS Bandwidth and Storage

GitHub and GitLab impose LFS storage limits:

Check your LFS usage:

git lfs ls-files --all
git lfs status

Common Errors

Practice Questions

Challenge

Create a repository, add a large file (create a 15 MB dummy file with dd if=/dev/zero of=large.dat bs=1M count=15), commit it, and note the repository size. Convert the file to LFS using git lfs migrate import. Compare repository sizes before and after. Verify the LFS pointer file is small by examining it with cat large.dat.

Real-World Task

You have a repository with 2 GB of design assets (PSD files, PNGs, and videos) committed without LFS. Use git lfs migrate to move the PSD and video files to LFS while keeping PNGs in regular Git (if they are small). Set up .gitattributes for future files. Force-push the rewritten history. Configure CI/CD to install LFS before builds. This migration pattern is used at DodaTech for DodaZIP's marketing site assets.

Built by the developers of Doda Browser, DodaZIP, and Durga Antivirus Pro.