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

By Daniel Zoghalchali·Latchkey

git sparse-checkout set limits which directories Git materializes in the working tree.

In a large monorepo, sparse-checkout lets a CI job check out only the paths it builds, cutting checkout time and disk. Cone mode keeps the patterns simple and fast.

What it does

git sparse-checkout set defines the set of paths present in the working tree; everything outside the patterns is left out. git sparse-checkout init enables the feature, and disable turns it off and restores a full checkout.

Common usage

git sparse-checkout init --cone
git sparse-checkout set apps/web libs/shared
git sparse-checkout list
git sparse-checkout disable

Options

Common errors in CI

An empty working tree after set usually means cone mode plus a path that does not exist, or non-cone patterns that match nothing - verify with git sparse-checkout list and that the paths exist in the commit. Combine with a partial clone (--filter=blob:none) to avoid downloading excluded blobs at all.

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.

- 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

Related guides

References

• GitHub Actions documentation