Git LFS fundamentals — pointers and object storage

Git LFS does not make the repository smaller. It moves the cost: large contents live in an external object store, Git tracks small pointers. Bandwidth shifts from git clone to git lfs pull; workflow shifts from git-native to LFS-aware; storage shifts from disk to a billed service.

The pointer model

When a file is LFS-tracked, Git commits a small text file: the LFS pointer.

version https://git-lfs.github.com/spec/v1
oid sha256:<hash>
size <bytes>

The oid is the SHA-256 of the contents; contents live in the LFS object store. A clone without git lfs pull reads pointers, not contents.

flowchart LR
    A["working tree"] -->|commit| B["pointer in Git"]
    B --> C["Git packfile"]
    B -->|"oid maps to"| D["LFS object store"]
    D -->|"git lfs pull"| A

The packfile holds the pointer. The object store holds the bytes. git lfs pull resolves pointers into real files.

Install, track, commit

git lfs install
git lfs track "*.bin"
git add .gitattributes
git add assets/data.bin
git commit -m "Track data.bin through LFS"

git lfs install installs clean/smudge filters once per user. git lfs track writes the pattern to .gitattributes; commit that file so teammates get the same filters.

git lfs ls-files
git lfs fetch
git lfs pull
git lfs prune

lfs ls-files lists tracked files with oids; lfs fetch downloads without checkout; lfs pull materialises; lfs prune removes orphans.

CI integration

A CI runner must fetch LFS objects before the build reads files. Without it, the build reads pointers and fails.

steps:
  - uses: actions/checkout@v4
    with:
      lfs: true
  - run: git lfs pull

lfs: true tells checkout to fetch LFS objects.

Production discipline

1. Track deliberately: rarely-revised immutables.
2. Commit .gitattributes immediately.
3. Migrate history only with planned rewrite.
4. Pre-warm CI runners.

Cross-course references

• Ansible for Production Sysadmins Part XXXVII: collections pinned by tag.
• Terraform for Production Sysadmins Part IX: state in a backend.

Quiz

Quiz