Git LFS: pointer files, smudge filters and when not to use it

What it is

Git LFS is a Git extension that, in the project's words, replaces large files such as audio samples, videos, datasets and graphics with text pointers inside Git while storing the contents on a remote server. The specification defines the pointer: a few key-value lines with version https://git-lfs.github.com/spec/v1, oid sha256:<hash> and size <bytes>. The tool hooks in through Git's clean and smudge filters, installed once with git lfs install; git lfs track "*.psd" writes the filter attributes into .gitattributes. Locally the real contents live under .git/lfs/objects/, sharded by the first hash characters, and are exchanged with the LFS server separately from the normal push and fetch.

Why it matters

Every version of a binary file stays in ordinary Git history forever and is downloaded by every clone. With LFS the history holds only pointers, and a clone fetches the contents for the checked-out commit. The price is a second system: an LFS endpoint with its own authentication, bandwidth and storage quotas, a client that must be installed on every machine and CI runner, and pointers that show up as three-line text files wherever the client is missing.

How to apply

• Track by pattern before the first large commit; the project page notes that tracking does not convert files already in history, which needs git lfs migrate.
• Commit .gitattributes with the LFS lines so all clones agree which paths are pointers.
• Install the client in CI images and use git lfs pull (or the host's LFS-aware checkout) where builds need the contents.
• Budget storage and bandwidth on the host's terms; check how objects that are no longer referenced are counted and purged.
• Do not use it for small files that change rarely; a checked-in icon set does not need a second server.
• Do not use it for build outputs, dependency archives or model weights that a package registry or object store already versions; a URL plus checksum in the repository is simpler.
• Do not use it when clones must work without network access to the LFS endpoint, or through tooling that does not run the smudge filter.
• Do not use it for text that merely happens to be large (generated JSON, fixtures); Git delta-compresses text well, and an LFS-tracked file is diffed only as its pointer.

Pitfalls

A push made from a machine without the LFS client (so without its pre-push hook) sends pointers whose objects never reach the server, and every other clone then finds those objects missing when it tries to fetch them. Forking and mirroring workflows must copy LFS objects too. Removing LFS later means rewriting history again.