# git sparse-checkout: Usage, Options & Common CI Errors

> git sparse-checkout limits the working tree to a subset of paths, speeding monorepo CI. Reference for init, set, --cone, list, and empty-tree errors.

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

git sparse-checkout populates only the directories you ask for, leaving the rest of a big repo out of your working tree.

Sparse checkout shrinks monorepo working trees so CI only materializes the paths a job needs.

## What it does

git sparse-checkout configures Git to check out only specified paths into the working tree while keeping the full repository in the object store. Cone mode optimizes for directory-based patterns.

## Common usage

```Terminal
git sparse-checkout init --cone
git sparse-checkout set apps/web libs/shared
git sparse-checkout list
git sparse-checkout disable
# clone sparse from the start:
git clone --filter=blob:none --sparse <url>
```

## Options

| Subcommand | What it does |
| --- | --- |
| init --cone | Enable sparse-checkout in cone mode |
| set <paths…> | Choose which directories to populate |
| add <paths…> | Add more paths to the set |
| list | Show the current sparse patterns |
| disable | Restore a full working tree |

## Common errors in CI

An empty working tree usually means set was never called (after init the tree may include only top-level files) or the paths do not match. In cone mode, patterns are directories, not globs; non-cone mode uses gitignore-style patterns - mixing them yields surprising results.

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

Sparse checkout shrinks monorepo working trees so CI only materializes the paths a job needs.

### What it does?

git sparse-checkout configures Git to check out only specified paths into the working tree while keeping the full repository in the object store. Cone mode optimizes for directory-based patterns.

### Common errors in CI?

An empty working tree usually means set was never called (after init the tree may include only top-level files) or the paths do not match. In cone mode, patterns are directories, not globs; non-cone mode uses gitignore-style patterns - mixing them yields surprising results.

---

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