🔀 Fix Large Files Checking Out as Tiny Text Pointers Because Git LFS Was Never Installed on That Machine
Git LFS works by replacing a large tracked file’s actual content in the repository with a small text pointer file containing an object ID and a byte size, and relying on a Git LFS client hook installed locally to transparently swap that pointer back out for the real binary content during checkout. On a machine where the git-lfs client was never installed, a fresh CI runner, a teammate’s new laptop, a Docker build stage that only installed git itself, git has no idea LFS pointers mean anything special; it checks out the pointer file exactly as committed, so a multi-megabyte asset shows up as a tiny, human-readable text file a few hundred bytes long instead of the real content.
🔎 The Problem
$ cat assets/hero-video.mp4 version https://git-lfs.github.com/spec/v1 oid sha256:4d7a214614ab2935c943f9e0ff69a... size 48213890 $ ls -la assets/hero-video.mp4 -rw-r--r-- 1 user user 134 Nov 14 10:02 assets/hero-video.mp4 # 134 bytes - that's the pointer file, not the real ~48MB video
✅ Fix: Install the LFS Client and Re-Checkout
- Install git-lfs on the machine before cloning or checking out a repository that uses LFS-tracked files, not after discovering pointer files are checked out, since git lfs install sets up the required smudge and clean filters.
- If the pointer files are already checked out, run git lfs pull after installing the client to replace the pointer text with the real binary content without needing a fresh clone.
- Add a git-lfs install step explicitly to CI and Docker build pipelines rather than assuming whatever base image or runner is used already has it; a plain git clone in a minimal image will not fetch real LFS content.
🚨 Why This Is Dangerous
- A build or deployment pipeline that silently ships the pointer text instead of the real asset doesn’t fail loudly; it produces a working-looking build with a broken video, image, or binary that only surfaces when someone actually opens it.
Git LFS keeps your repository small by handing you a promise instead of the file — and a machine without the LFS client never redeems that promise.

