# git lfs: Usage, Options & Common CI Errors

> git lfs (Large File Storage) stores big files outside the repo via pointers. Reference for install, track, pull, and pointer-not-fetched/quota errors.

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

git lfs replaces large files in your repo with small pointers, storing the real content separately.

LFS keeps repos small but adds a fetch step. CI that forgets it ends up with pointer files instead of real assets.

## What it does

git lfs is an extension that swaps large files for text pointers tracked in Git, while the binary content lives on an LFS server and is fetched on checkout when LFS is installed.

## Common usage

```Terminal
git lfs install
git lfs track "*.psd"
git lfs pull                       # download LFS objects
git lfs ls-files
git lfs fetch --all
```

## Options

| Subcommand | What it does |
| --- | --- |
| install | Set up the LFS Git hooks |
| track <pattern> | Track a path pattern with LFS |
| pull | Fetch and check out LFS content |
| ls-files | List LFS-managed files |
| fetch --all | Download all LFS objects |

## Common errors in CI

Files contain "version https://git-lfs.github.com/spec/v1" text instead of real content - LFS objects were not pulled. Run git lfs install then git lfs pull (in actions/checkout set lfs: true). "batch response: This repository is over its data quota" means LFS bandwidth/storage limits were hit.

## 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: Usage, Options & Common CI Errors?

LFS keeps repos small but adds a fetch step. CI that forgets it ends up with pointer files instead of real assets.

### What it does?

git lfs is an extension that swaps large files for text pointers tracked in Git, while the binary content lives on an LFS server and is fetched on checkout when LFS is installed.

### Common errors in CI?

Files contain "version https://git-lfs.github.com/spec/v1" text instead of real content - LFS objects were not pulled. Run git lfs install then git lfs pull (in actions/checkout set lfs: true). "batch response: This repository is over its data quota" means LFS bandwidth/storage limits were hit.

---

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