git lfs Command: Large Files in CI

By Kaveh Alemi·Latchkey

git lfs (Large File Storage) replaces big files with pointers and fetches their content on demand.

When a repo uses LFS, a plain clone gives you pointer text files instead of real assets. CI must initialize LFS and pull the objects, or the build sees placeholder files.

Common flags

install - set up the LFS hooks and filters for the user or repo
install --local - install hooks only for the current repository
pull - download LFS objects and replace pointers in the working tree
fetch - download LFS objects without updating the working tree
checkout - populate working-tree files from already-fetched objects
env - print LFS configuration for debugging

Example

shell

# Ensure LFS assets are real files, not pointers, in CI
git lfs install --local
git lfs pull

In CI

If a build fails because an image or binary is a tiny text file starting with "version https://git-lfs", LFS was not pulled. Run git lfs install then git lfs pull (or set lfs: true in your checkout action). Caching LFS objects between runs avoids re-downloading large assets.

Using this in CI

CI checkouts are shallow and detached by default, which changes the answer this command gives you. Commands that read history, branch names, or tags need the checkout configured for it.

.github/workflows/ci.yml

- uses: actions/checkout@v4
  with:
    fetch-depth: 0   # history, tags, and git describe all need this

- run: |
    git rev-parse --is-shallow-repository   # expect false
    git rev-parse --abbrev-ref HEAD          # prints HEAD when detached

Key takeaways

Without git lfs pull, CI sees pointer files instead of real large assets.
git lfs install sets up the filters; git lfs pull fetches the content.
A text file starting with "version https://git-lfs" is an unpulled pointer.

Frequently asked questions

git lfs Command: Large Files in CI?