Git LFS Checkout Shows Pointer Files in Unity - Smudge Filter and .lfsconfig Fix

Problem: After cloning or checking out a Unity branch, textures, audio, or models appear broken, and files contain pointer text like version https://git-lfs.github.com/spec/v1 instead of binary asset data.

This issue usually means Git LFS did not download real file content during checkout because the smudge filter was disabled, misconfigured, or blocked.

Quick fix checklist

Confirm Git LFS is installed and available in your shell.
Validate LFS filters are configured (clean, smudge, process).
Ensure .gitattributes tracks Unity binary formats (.psd, .fbx, .wav, etc.).
Check .lfsconfig and remote URL alignment.
Rehydrate the working copy with git lfs pull and a fresh checkout.

Root cause summary

Most Git LFS pointer file problems in Unity come from one of these:

LFS not installed on machine - checkout leaves pointer text untouched.
Smudge disabled - GIT_LFS_SKIP_SMUDGE=1 or broken filter config blocks download.
Bad track rules - files were committed as normal Git blobs or mixed states.
Auth/remote mismatch - LFS server requests fail silently in some setups.

Step-by-step fix

Step 1 - Verify Git LFS is active

Run:

git lfs version

If command fails, install Git LFS and then run:

git lfs install

Verification: git lfs env shows configured filters and endpoint URLs.

Step 2 - Validate filter configuration

Check these Git settings:

filter.lfs.clean
filter.lfs.smudge
filter.lfs.process
filter.lfs.required

If missing, run git lfs install again in your user environment.

Common mistake: Keeping GIT_LFS_SKIP_SMUDGE=1 set globally from CI scripts.

Step 3 - Confirm tracked file patterns

Open .gitattributes and ensure Unity binary assets are LFS-tracked (for example: *.psd, *.fbx, *.wav, *.mp4, *.blend).

If required patterns are missing:

Add them via git lfs track.
Commit updated .gitattributes.
Recommit affected assets if they were stored as wrong object type.

Step 4 - Check .lfsconfig and remote endpoint

If your project uses .lfsconfig, verify:

URL points to the correct LFS host
You can authenticate to that endpoint
Repo remote and LFS endpoint belong to the same project/org

Verification: git lfs ls-files lists tracked files and git lfs pull completes without auth errors.

Step 5 - Rehydrate pointer files safely

After config is fixed:

Fetch and pull LFS objects (git lfs fetch --all then git lfs pull).
Re-checkout current branch to replace pointer files with binaries.
Reopen Unity and allow asset reimport.

If pointers remain, remove one affected file and checkout just that path from HEAD to force re-materialization.

Alternative fixes

Clone again into a fresh folder after confirming LFS setup.
If repo migration broke LFS references, run a one-time LFS migration on a maintenance branch.
For CI agents, set explicit git lfs pull step after checkout.

Prevention tips

Add a preflight script that fails build when pointer text is detected in Assets/.
Keep .gitattributes reviewed under code ownership.
Avoid global SKIP_SMUDGE on developer machines.
Document required Git + LFS versions in your project README.

FAQ

Why do only some Unity assets become pointer files?
Only patterns tracked by LFS and checked out without hydration are affected. Mixed history can cause partial failures.

Is git lfs pull enough every time?
Usually yes after filters are correct. If history is mixed, you may need to recommit affected files.

Can this break Unity GUID references?
Not usually if .meta files stay intact. The main failure is missing binary content, not GUID remapping.