Git LFS for Unity: Fix ‘File Exceeds 100 MB’ Push Errors

You push your Unity project and GitHub rejects it: “File Assets/Audio/music.wav is 112 MB; this exceeds GitHub’s file size limit of 100.00 MB.” Or the repo has grown to several gigabytes and every clone takes forever. Unity Git LFS for large files solves both: big binary assets are stored outside the normal git history and downloaded only when needed. This guide covers setting up LFS for a Unity project, what to track, fixing a push that’s already been rejected, and the quotas to watch.

What Git LFS Does

Git stores every version of every file forever. A text script changing 20 times costs little; a 50 MB texture changing 20 times adds 1 GB to every clone. Git LFS (Large File Storage) replaces large files in the repository with small pointer files and keeps the real content on an LFS server. When you check out a commit, LFS downloads only the versions that commit needs.

For Unity, this means textures, audio, models, videos and other binaries go to LFS, while scripts, scenes, prefabs and .meta files stay in normal git so they can be diffed and merged.

Install and Set Up LFS

1. Install Git LFS. It ships with Git for Windows and GitHub Desktop; on macOS use brew install git-lfs.
2. Enable it once per machine:

git lfs install

3. In your project root, add patterns to track. Each command adds a line to .gitattributes:

git lfs track "*.psd"
git lfs track "*.png"
git lfs track "*.wav"
git add .gitattributes
git commit -m "Track binary assets with Git LFS"

Do this before adding the large files. Files committed before tracking stay in normal git history (see the migration section). If you’re starting a project from scratch, follow the git setup guide first, then add LFS.

What to Track in a Unity Project

A solid starting .gitattributes LFS section:

# Images
*.png  filter=lfs diff=lfs merge=lfs -text
*.jpg  filter=lfs diff=lfs merge=lfs -text
*.tga  filter=lfs diff=lfs merge=lfs -text
*.psd  filter=lfs diff=lfs merge=lfs -text lockable
*.exr  filter=lfs diff=lfs merge=lfs -text
*.hdr  filter=lfs diff=lfs merge=lfs -text
# Audio
*.wav  filter=lfs diff=lfs merge=lfs -text
*.mp3  filter=lfs diff=lfs merge=lfs -text
*.ogg  filter=lfs diff=lfs merge=lfs -text
# Models
*.fbx  filter=lfs diff=lfs merge=lfs -text
*.blend filter=lfs diff=lfs merge=lfs -text lockable
*.obj  filter=lfs diff=lfs merge=lfs -text
# Video and other binaries
*.mp4  filter=lfs diff=lfs merge=lfs -text
*.ttf  filter=lfs diff=lfs merge=lfs -text
*.otf  filter=lfs diff=lfs merge=lfs -text
*.dll  filter=lfs diff=lfs merge=lfs -text
*.so   filter=lfs diff=lfs merge=lfs -text
*.a    filter=lfs diff=lfs merge=lfs -text
*.unitypackage filter=lfs diff=lfs merge=lfs -text

Don’t track .unity, .prefab, .asset, .mat, .meta or .cs with LFS. They’re text, they merge, and Unity Smart Merge only works on them in normal git. The merge conflicts guide covers handling those. Large baked lighting data (LightingData.asset) is the one .asset sometimes worth tracking, because it’s big and binary in practice; you can track that by path.

Fixing a Rejected Push

If GitHub already rejected your push because of a file over 100 MB, adding LFS tracking now isn’t enough: the big file is still inside an earlier commit you’re trying to push. You need to rewrite those local commits so the file is stored in LFS.

If the commits haven’t been pushed anywhere yet, migrate them:

git lfs migrate import --include="*.wav" --include-ref=refs/heads/main

This rewrites the history of main so every .wav is an LFS pointer, and adds the pattern to .gitattributes. Then push normally. Replace the pattern with whatever file types are too large. Back up the project folder first; history rewrites are hard to undo.

Moving Existing Files to LFS

For a project already on the remote, you have two choices:

• Going forward only: run git lfs track, then git add --renormalize . and commit. Current files move to LFS from now on; old versions stay in git history, so the repo doesn’t shrink, but it stops growing fast.
• Rewrite everything: git lfs migrate import --everything --include="*.png,*.wav,*.fbx", then force-push. The repo shrinks, but every collaborator must re-clone, and open branches need rebasing. Coordinate with your team before doing this.

Check what’s taking space with git lfs migrate info --everything, which lists file types by size.

Locking Binary Files

Binary files can’t be merged, so two people editing the same PSD means one loses work. Patterns marked lockable become read-only on checkout until you lock them:

git lfs lock Assets/Art/Hero.psd
# edit, commit, push
git lfs unlock Assets/Art/Hero.psd
git lfs locks   # see who has what locked

Locking requires a host that supports the LFS locking API, which GitHub, GitLab and Bitbucket do.

Storage and Bandwidth Limits

LFS hosting has quotas. Free plans on the big hosts include a limited amount of LFS storage and monthly bandwidth, and every clone, CI run and pull downloads LFS content, which counts against bandwidth. Heavy art projects can hit limits quickly. Check your host’s current LFS pricing, and:

• Use GIT_LFS_SKIP_SMUDGE=1 or git lfs pull --include on CI to download only what the build needs.
• Don’t commit raw source files you never change (huge uncompressed recordings); store them elsewhere.
• Consider a host with larger LFS allowances, or Unity Version Control, for art-heavy teams.

Troubleshooting

“this exceeds GitHub’s file size limit of 100.00 MB”

The file is in a commit as a normal git object. Use git lfs migrate import on the unpushed commits, then push.

Textures appear as tiny text files in Unity

LFS isn’t installed on that machine, so pointers were checked out. Run git lfs install, then git lfs pull.

“Encountered N files that should have been pointers, but weren’t”

Files matching an LFS pattern were committed before tracking. Run git add –renormalize . and commit.

Push hangs or is very slow

Large LFS uploads take time. Check progress with GIT_TRACE=1, and avoid committing huge files repeatedly.

“This repository is over its data quota”

LFS storage or bandwidth limit reached. Buy more, clean up, or move to another host.

FAQ