🔀 The Clone That Downloaded a Text File Pretending to Be Your Binary
Large File Storage replaces tracked binary files with small text pointer files inside the actual repository history, and relies on a separate filter configured per machine to swap those pointers back for the real content on checkout. Clone the repository with a tool, a CI image, or a minimal installation that never had that filter configured, and the checkout produces exactly the pointer files as stored in history – small, valid-looking text files with the wrong extension, that open as garbled text instead of the real image, video, or binary asset they are meant to represent.
🔎 The Problem
$ git clone https://example.com/repo.git $ cat assets/hero-banner.psd version https://git-lfs.github.com/spec/v1 oid sha256:4d7a9c3b1e... size 48213920 # That is the entire file on disk - 130 bytes, not the 48 MB file it # is supposed to be. Opening it anywhere fails or shows garbage, # because there is no binary content here yet, just the pointer the # filter was supposed to resolve on checkout. # The fix starts with registering the filter ONCE per machine, then # re-pulling to replace the pointers with real content: $ git lfs install $ git lfs pull
✅ Fix: Install the Filter Once Per Machine, Then Re-Pull
- Run the install step once on every machine or CI image that will clone a repository using Large File Storage – it registers the checkout filter Git needs to resolve pointer files into real content, and a fresh operating system image or container almost never has it unless you add it explicitly.
- On a machine that already has an affected clone, re-pull the tracked content after installing the filter instead of re-cloning the whole repository – it resolves the existing pointer files in place without needing to download everything again.
- For CI pipelines specifically, confirm the checkout step actually fetches the tracked content, since many checkout actions have that support turned off by default – a build that silently operates on pointer files instead of real assets can pass by accident on tests that never actually open the file.
⚠️ Why This Is Easy to Miss
- A pointer file is a syntactically valid, small text file – nothing about the clone itself errors or warns you, so the problem only becomes visible once something downstream actually tries to open or process the file’s real content.
- A developer’s own laptop usually has the filter installed once, globally, from whenever they first set it up, so the gap in a fresh CI image or a new teammate’s machine is easy to overlook as something that has never been a problem before.
A pointer file is a perfectly honest description of where your binary is supposed to come from – it is just not, itself, the binary.