Git LFS Tutorial for Game Developers: Handling Large Assets Without Breaking Your Repo

If you’ve ever tried to push a 2GB 4K texture pack or a high-poly FBX model to a standard Git repository, you know the pain. Git is designed to track text changes line-by-line; it absolutely hates large binary files. Every time you change one pixel in a massive PNG, Git saves a whole new copy of that file in your history, leading to a repository that grows exponentially until git clone takes three hours.

That’s where Git Large File Storage (LFS) comes in. In this git lfs tutorial for game developers, I’ll walk you through how to offload your heavy assets to a dedicated store while keeping lightweight pointers in your main repo. This is the standard way to handle Unity, Unreal, or Godot projects without switching to a fully proprietary system like Plastic SCM.

Prerequisites

Before we dive in, make sure you have the following installed and configured:

Git: The core version control system.
A Hosting Provider: GitHub, GitLab, or Bitbucket (all support LFS, though storage limits vary).
Admin Access: You’ll need permissions to modify the repository settings.

Step 1: Installing and Initializing Git LFS

Git LFS isn’t built into Git by default; it’s an extension. I’ve found that installing it once globally on your machine is the smoothest workflow.

# Install Git LFS on your system (macOS example) 
brew install git-lfs

# Initialize LFS for your user account (only do this once ever)
git lfs install

Once you’ve run git lfs install, your local Git configuration is updated to handle LFS pointers. Now you just need to tell Git which files should be treated as “large.”

Step 2: Tracking Game Assets

You don’t want to track everything with LFS—only binary files. Text files (scripts, shaders, project settings) should stay in standard Git. For game devs, this usually means textures, meshes, audio, and compiled binaries.

Here is how I typically set up a Unity or Unreal project. Run these commands from your project root:

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

# Track all FBX models and Maya files
git lfs track "*.fbx"
git lfs track "*.maya"

# Track all high-res textures
git lfs track "*.tga"
git lfs track "*.png"
git lfs track "*.jpg"

# Track audio files
git lfs track "*.wav"
git lfs track "*.mp3"

When you run these commands, Git creates or updates a file called .gitattributes. This file is the “map” that tells every other developer on your team which files are LFS assets. Crucially, you must commit this file to your repo.

git add .gitattributes
git commit -m "Configure Git LFS for textures, models, and audio"

As shown in the image below, the .gitattributes file ensures that when a teammate clones the repo, their Git client knows to fetch the binary data from the LFS server rather than expecting it in the main history.

The .gitattributes file configuration for Git LFS in a game project

Step 3: Normal Workflow and Pushing

From here, your workflow doesn’t change. You git add, git commit, and git push exactly as you always have. The magic happens under the hood: Git replaces the massive binary file with a tiny text pointer, and the actual file is uploaded to the LFS cache.

# Add your new 500MB character model
git add Assets/Models/HeroCharacter.fbx
git commit -m "Add high-poly hero model"
git push origin main

Pro Tips for Game Devs

Use .gitignore alongside LFS: Don’t track your Library/ (Unity) or Intermediate/ (Unreal) folders at all. LFS is for assets you need, not generated cache.
Locking Files: One of the biggest headaches in game dev is merge conflicts in binary files (which are impossible to resolve). Use git lfs lock to prevent other team members from editing a file while you are working on it.
Pruning Old Assets: Over time, your LFS storage can bloat. Use git lfs prune to delete old versions of assets from your local disk that are already backed up on the server.

Troubleshooting Common Issues

“I committed the large file BEFORE I started using LFS!”
This is the most common mistake. If you’ve already committed a 1GB file, simply adding it to .gitattributes won’t shrink your repo history. You’ll need to rewrite your history using a tool like BFG Repo-Cleaner or git lfs migrate. If you’re dealing with massive datasets or similar issues in other fields, check out my thoughts on version control for machine learning models, as they face identical binary bloat challenges.

“My teammates are seeing text pointers instead of images.”
This usually means they haven’t run git lfs install on their local machine. Have them run the install command and then git lfs pull to fetch the actual binary data.

What’s Next?

Now that your assets are managed, you should look into optimizing your .gitignore to ensure you aren’t tracking unnecessary metadata. If you find that Git LFS is still too slow for your team’s scale (especially with 100GB+ projects), it might be time to evaluate a dedicated game VCS. I’ve spent a lot of time comparing these, and my Plastic SCM review provides a detailed look at the alternatives.