The Problem: When Git Becomes Sluggish Due to Heavy Files
Have you ever pushed a 500MB video file to GitHub and watched the progress bar crawl like a snail? Even worse, after waiting 15 minutes, you get a File exceeds 100MB limit error. You are not alone.
I once worked on a Computer Vision project with over 2,000 RAW images (~15GB). Not knowing about Git LFS at the time, I casually committed everything to the repo. As a result, every time a colleague ran git clone, it took them an hour to download a total mess. In reality, they only needed a few lines of code to get to work.
By nature, Git is designed to manage source code (text files). It stores history by recording the differences (diffs) between versions. However, with binary files like images, videos, or AI models, Git cannot calculate “diffs” effectively. If you change just 1 pixel in a 10MB image, Git will store another 10MB copy. Your .git folder will bloat rapidly.
Git LFS (Large File Storage) was created to solve this problem. It replaces heavy files with lightweight “pointers” that are only a few KB in size.
Quick Start: Configure Git LFS in 5 Minutes
Forget the dry theory; let’s get practical. Suppose you need to manage a 200MB file named video_demo.mp4.
Step 1: Install the Tool
Depending on your operating system, use the following commands:
- macOS:
brew install git-lfs - Ubuntu/Debian:
sudo apt install git-lfs - Windows: Download the installer from the official site
git-lfs.github.com.
Step 2: Initialize LFS
git lfs installYou only need to run this command once on your computer.
Step 3: Specify file types to track
For example, I want LFS to manage all .mp4 files:
git lfs track "*.mp4"At this point, a .gitattributes file will appear. It acts as a “gatekeeper,” telling Git: “Don’t touch these mp4 files, let LFS handle them.”
Step 4: Commit and Push
git add .gitattributes
git add video_demo.mp4
git commit -m "Add demo video using LFS"
git push origin mainIt’s that simple! The video file has been pushed to a separate storage server. Your repo is now extremely lightweight.
How It Works: Why is LFS So Fast?
Instead of stuffing a 200MB file into the .git folder, LFS only stores a pointer file with content like this:
version https://git-lfs.github.com/spec/v1
oid sha256:a7c2... (file identifier hash)
size 209715200When you run git checkout, Git LFS reads this pointer and downloads the actual file from the server. If you don’t switch to the branch containing that file, your machine won’t use a single byte of storage for it. This is the secret to keeping clone speeds lightning-fast for large projects.
Real-world Experience: Rescuing a Bloated Repo
A common mistake is only starting to track new files when the repo is already several GBs large. This doesn’t help because old files still remain in the commit history. Git won’t automatically delete old data unless you intervene deeply.
To clean it up thoroughly, I usually use the migrate command:
git lfs migrate import --include="*.zip,*.psd" --everythingWarning: This command will rewrite your entire commit history. Notify your team before running it, as everyone will need to git clone from scratch to avoid structural conflicts.
Optimizing Local Storage
Over time, your machine might run out of space because LFS keeps old versions for fast branch switching. To free up space, use:
git lfs pruneThis command deletes old LFS files from the local cache while keeping them safe on the server. If you need an older version later, Git will automatically download it.
Notes on Cost and Bandwidth
Git LFS is powerful but not entirely free on Cloud platforms:
- GitHub: 1GB of storage and 1GB of bandwidth per month for free. If you exceed this, you’ll need to buy a plan (around $5/month for 50GB).
- Self-hosted: If you use Gitea or GitLab installed on your own VPS, you can configure storage freely without worrying about third-party fees.
Tips for Game and Graphics Teams: File Locking
In Unity or Unreal projects, binary files like .psd or .fbx cannot be merged. If two people edit the same image file, a conflict is inevitable.
git lfs track "*.psd" --lockableWhen a designer edits a file, they run git lfs lock character.psd. Others will see the file is locked and won’t be able to push over it. This is an extremely effective way to prevent data loss.
Conclusion
Don’t wait until your repo is several GBs large to find a solution. As soon as you start a project with media, set up .gitattributes immediately. This makes the team’s workflow much smoother and more professional. If you encounter any errors during installation, feel free to leave a comment, and I’ll help you out!
