Skip to content
Tutorials Center
My learning

Topics

Git Reference ยท Files and Formats

The sparse-checkout file

Reference for .git/info/sparse-checkout: how cone mode and non-cone patterns decide which paths appear in the working tree, with examples and pitfalls.

The sparse-checkout file lives at .git/info/sparse-checkout (for a linked worktree, in that worktree's private Git directory). When sparse checkout is enabled, Git reads it to decide which tracked paths are materialized in the working tree. Everything else stays in the repository and in the index, but is marked "skip-worktree" and has no file on disk.

You rarely edit the file by hand: git sparse-checkout writes it for you. Knowing its format still matters, because the two modes (cone and non-cone) produce very different files, and because the file is what you inspect when a path is missing.

Terminal
git sparse-checkout set docs src/app   # cone mode: whole directories
cat .git/info/sparse-checkout

Try it

Bash What cone mode writes

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Bash Non-cone patterns by hand

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Syntax

When core.sparseCheckout is true, each line of the file is a pattern. Blank lines and lines starting with # are ignored.

Non-cone mode uses the same pattern language as .gitignore, but with the opposite meaning: a pattern that matches is included in the working tree, and a pattern starting with ! excludes. The last matching pattern wins. Patterns can be anchored with a leading /, a trailing / matches directories only, and *, ?, [] and ** work as in glob patterns.

Cone mode (core.sparseCheckoutCone=true) restricts the file to a fixed shape, which Git can match with fast hash lookups instead of testing every pattern. A cone-mode file looks like this:

TEXT
/*
!/*/
/src/
!/src/*/
/docs/
/src/app/

The first two lines include all files at the top level and exclude every top-level directory. Choosing src/app adds /src/ (so its files are included) followed by !/src/*/ (its subdirectories are excluded again), then /src/app/ includes that one subdirectory completely. Parents contribute their direct files, never their other subdirectories.

Setting Description
core.sparseCheckout true turns the feature on and makes Git read the file.
core.sparseCheckoutCone true selects cone mode; false or unset means non-cone.
index.sparse Optional: store the index itself in sparse form (requires cone mode).

Edge cases: if the file is missing or empty while sparse checkout is on, Git treats it as "include nothing", so a hand-made mistake can empty your working tree. Re-run git sparse-checkout disable to bring everything back.

Usage notes

  • Cone mode is the default for git sparse-checkout init and set since Git 2.37. Use --no-cone to get pattern matching.
  • Top-level files are always included in cone mode. You cannot select a single file inside a directory: the unit is the directory. Use non-cone mode when you need single files or extension filters.
  • Non-cone mode is slower on big trees, because every path is tested against every pattern. Git discourages it for large repositories.
  • Patterns affect the working tree, not history. Commits, diffs between revisions and git log -- path still see every path.
  • Changes are applied when the file is read. Editing by hand needs a following git read-tree -mu HEAD or git sparse-checkout reapply to update the files on disk.
  • Skipped files show as S in git ls-files -t. They are not "deleted" in git status.
  • Untracked files in excluded directories are left alone; Git will not remove a directory that still has files it did not put there.
  • Do not copy the file between clones assuming it works: it is per repository and per worktree, and the mode setting must match its format.