What does Git's sparse-checkout cone mode do, and how does it pair with a partial clone?
answer
- Index still complete, disk is not
- A per-file index bit is doing the work
- Directory prefixes instead of globs
- Shrinks the checkout, not the download
- Pairs with a blob filter at clone time
basics
~20 sgit sparse-checkout limits which directories are materialized in the working tree, marking the rest skip-worktree in the index. Cone mode restricts patterns to whole directory prefixes so matching stays fast. It shrinks the checkout, not the download; a partial clone shrinks the download.
solid answer
~40 s`git sparse-checkout` tells Git which paths to actually write into the working tree; entries outside the selection stay in the index with the `skip-worktree` bit set, so `git status` ignores them and they never hit disk. **Cone mode** restricts the pattern language to directory prefixes rather than arbitrary gitignore-style globs, which lets Git decide inclusion by directory lookup instead of matching every path against every pattern — the difference between usable and painful on a very large tree. You drive it with `git sparse-checkout set <dir> <dir>`, `add`, `list`, `reapply` and `disable`; the patterns live in `.git/info/sparse-checkout`. Crucially it does not reduce what you download: history and objects for the whole repository still arrive unless you combine it with `--filter=blob:none`, which is why `git clone --filter=blob:none --sparse` is the usual pairing.
code
bash · 8 linesgit clone --filter=blob:none --sparse https://example.com/big.git
cd big
git sparse-checkout set services/payments libs/common
git sparse-checkout list
# services/payments
# libs/common
git ls-files | wc -l # index still lists every tracked path
ls # only the selected directories on diskgo deeper
Know that sparse checkout limits which directories appear on disk while the repository still tracks everything, and that git sparse-checkout set names the directories you want.
Explain the skip-worktree bit, where the patterns live, and why cone mode's directory-prefix rule is cheaper to evaluate than gitignore-style matching.
Show that you separate the three axes — history depth, object transfer, working-tree size — and can say which one a given complaint is actually about before changing a clone command.
Weigh whether a path-scoped developer experience is worth the tooling breakage it introduces, and decide who owns keeping build tools honest when the working tree is deliberately incomplete.
## The problem it solves A very large repository can have a working tree that is painful for reasons unrelated to network transfer: hundreds of thousands of files to write, `git status` scanning them all, editors and watchers indexing directories nobody on the team touches. Sparse checkout addresses the *working tree*, which is a separate axis from history depth and object transfer. ## The mechanism The index still lists every tracked path — Git's idea of the commit is unchanged. For paths outside the sparse selection, Git sets the `skip-worktree` bit on the index entry. That bit tells Git "do not expect this file on disk, and do not report it as deleted". Checkout writes only the selected paths; `git status` stays quiet about the rest. Because the index is complete, commits you create still contain the whole tree. Sparse checkout is not a way to remove files from history or from a commit; it only changes what is materialized locally. ## Cone mode versus pattern mode The original sparse-checkout accepted gitignore-style patterns in `.git/info/sparse-checkout`. That is expressive but slow: every path in the index must be tested against every pattern, and the rules are easy to get subtly wrong. **Cone mode** restricts you to directory paths. The selection becomes: all files in the repository root, plus every file under each named directory, plus the files in the parent directories leading to them. Because the rule is a directory-prefix decision, Git can evaluate it with a hash lookup per directory instead of a full pattern match, and it can skip entire subtrees at once. In recent Git, `git sparse-checkout set <dirs>` uses cone mode by default; `--no-cone` opts back into full pattern matching. The related commands are `git sparse-checkout list` (show the current selection), `add` (extend it), `reapply` (re-evaluate after the index or config changed) and `disable` (return to a full checkout). ## Pairing with partial clone Sparse checkout by itself still downloads everything: all commits, all trees, all blobs. If the goal is a smaller clone and not just a smaller working tree, pair it with a partial clone: `git clone --filter=blob:none --sparse <url>` transfers the graph without file contents, initializes a minimal sparse checkout at the repository root, and then fetches blobs only for the directories you actually select. That combination is what makes a huge repository workable on a laptop or in a path-scoped CI job. ## Where it bites - **Commands still see everything.** `git grep`, `git log -- <path>` and merges operate over the full tree; in a partial clone those may trigger lazy fetches for paths you never checked out. - **Merges and rebases touching excluded paths** are resolved from the index and objects, not from files on disk. That normally works, but a conflict in an excluded path is confusing because the file is not there to edit — Git will materialize it when it must. - **Tooling assumptions.** Build systems that glob the working tree see a partial repository and may conclude modules are missing. This is the most common source of "it works for me" reports. - **It is not access control.** Every excluded file is still in the object store or one fetch away; sparse checkout hides paths for convenience, never for confidentiality. ## When to reach for it Use it when engineers or CI jobs legitimately work on a bounded slice of a large tree and the checkout cost is measurable. Skip it when the repository is small enough that the full checkout is not a real cost — the added tooling confusion is not worth it.
- Does sparse checkout change what a commit you create contains?No. The index still holds every tracked path, so a commit records the complete tree exactly as a full checkout would. Only materialization on disk changes. This is why sparse checkout is safe to use mid-project, and why it can never be used to drop files from a commit.
- Why is cone mode faster than the older pattern mode?Pattern mode tests every index entry against every gitignore-style pattern. Cone mode restricts patterns to directory prefixes, so Git answers inclusion with a lookup on the directory and can exclude an entire subtree in one decision instead of per file. On a tree with hundreds of thousands of paths that is the difference between snappy and unusable.
- Is sparse checkout a way to keep sensitive directories away from a developer?No. Everything is still reachable: in a full clone the objects are already local, and in a partial clone one command fetches them. It is an ergonomics and performance feature. Confidentiality requires the content not to be in the repository the person can clone at all.
- Thinks excluded paths are removed from commits
- Believes sparse checkout reduces the amount downloaded
- Uses it as an access-control mechanism
- Assumes cone mode supports arbitrary glob patterns
- Reports excluded files as deleted in status
assumes recent Git (2.3x+), where git sparse-checkout set uses cone mode by default and git clone accepts --sparse
context
- Q-09388How does a Git partial clone with --filter=blob:none differ from a shallow clone?level: middleimportance: should knowfreq 42%