How to Set Up and Use Git LFS (Large File Storage)

In this tutorial, you'll learn about How to Set Up and Use Git LFS (Large File Storage). We cover key concepts, practical examples, and best practices.

The Problem

You try to push a 200 MB design file or dataset to GitHub and get error: GH001: Large files detected. You must use Git LFS to track these files. Git is not designed for binary files — every version of a large file stays in the repository history forever, making clones slow and the repo bloated. Git LFS replaces large files with text pointers in the repo and stores the actual content on a remote server.

Quick Fix

1. Install Git LFS

# Linux
sudo apt-get install git-lfs

# macOS
brew install git-lfs

# Windows (included with Git for Windows)
git lfs install

# Verify
git lfs version

2. Track specific file patterns

git lfs track "*.psd"
git lfs track "*.zip"
git lfs track "*.mp4"
git lfs track "assets/**/*.png"

This creates/modifies a .gitattributes file. Commit it:

git add .gitattributes
git commit -m "Configure Git LFS tracking"

3. Verify tracked patterns

git lfs track

Expected output:

Listing tracked patterns
    *.psd (.gitattributes)
    *.zip (.gitattributes)
    assets/**/*.png (.gitattributes)

4. Migrate existing large files to LFS

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

This rewrites history to store those files through LFS. Force push after:

git push --force origin main

5. Clone a repo with LFS files

git clone git@github.com:user/repo.git
cd repo
git lfs pull

# Clone with LFS files included automatically
GIT_LFS_SKIP_SMUDGE=0 git clone git@github.com:user/repo.git

6. Check LFS storage usage

git lfs ls-files --all
git lfs status

7. Set up LFS in CI/CD

# GitHub Actions
- name: Checkout
  uses: actions/checkout@v4
  with:
    lfs: true

Common Causes

Practice with a Test Repository

cd /tmp
mkdir git-practice && cd git-practice
git init --initial-branch=main
# Initialized empty Git repository in /tmp/git-practice/.git/
echo "test" > file.txt && git add . && git commit -m "init"
# [main (root-commit) abc1234] init

Before running destructive commands on your real repository, practice on a throwaway test repository. This builds confidence and prevents costly mistakes. The reflog is your safety net, but practice makes it less needed.

Prevention

• Set up .gitattributes and commit it before adding large files to the repo
• Use git lfs migrate import proactively for repos with existing large files
• Check your hosting provider's LFS storage limits (GitHub: 1 GB free, GitLab: varies)
• Add git-lfs to your team's setup docs so everyone has it before cloning