# git lfs Command: Large Files in CI

> git lfs manages large files stored outside Git. Reference for git lfs install and git lfs pull to fetch large assets correctly in CI checkouts.

Source: https://latchkey.dev/learn/command-reference/git-lfs-command-reference  
Updated: 2026-06-26

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
```

> `git rev-parse --abbrev-ref HEAD` returns the literal string `HEAD` on a detached checkout rather than a branch name. On GitHub Actions read `github.ref_name` instead; the git command cannot know what it was checked out for.

## FAQ

### git lfs Command: Large Files in CI?

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.

### 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.

---

Latchkey runs CI/CD that repairs its own failures. Agent entry points: https://latchkey.dev/agent.txt, https://latchkey.dev/openapi.json, https://latchkey.dev/llms.txt