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

By Kaveh Alemi·Latchkey

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

Frequently asked questions

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