git sparse-checkout Command in CI

By Kaveh Alemi·Latchkey

git sparse-checkout populates the working tree with only the directories you list.

In a large monorepo, a CI job often needs just one package. Combined with a partial clone, sparse-checkout keeps the working tree (and disk and time) small.

Common flags

init --cone - enable sparse checkout in cone mode (directory-based, fast)
set <dir>... - restrict the working tree to the given directories
add <dir> - add more directories to the sparse set
list - show the current sparse patterns
disable - turn sparse checkout off and restore the full tree
reapply - re-evaluate patterns against the index

Example

shell

# Check out only one service from a monorepo
git clone --no-checkout --filter=blob:none \
  https://github.com/owner/monorepo.git repo
cd repo
git sparse-checkout init --cone
git sparse-checkout set services/billing
git checkout main

In CI

Pair --filter=blob:none with sparse-checkout in cone mode to clone a monorepo quickly and materialize only the package a job builds. Cone mode is much faster than the pattern-matching default and is the recommended choice for CI.

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

sparse-checkout in cone mode materializes only the directories a CI job needs.
Combine it with --filter=blob:none for a fast, small monorepo checkout.
Cone mode outperforms the legacy pattern mode and is preferred in CI.

Frequently asked questions

git sparse-checkout Command in CI?