Git Sparse-Checkout: Work with a Selected Working-Tree Subset

Advanced

What sparse-checkout changes

A sparse checkout changes which tracked paths are populated in the working tree. The omitted paths remain tracked; they are not deleted from history or converted into untracked files. Git records the sparse specification and uses index state to decide which tracked files should be present.

git sparse-checkout init --cone
git sparse-checkout list

A sparse-checkout is being configured.?Only the selected subset is populated; omitted paths remain tracked.

Cone mode: select directories

Cone mode is the normal directory-oriented mode. You specify directories, and Git populates those directories plus the leading directory structure needed to reach them. It is designed for the common case where a developer wants whole directory subtrees rather than arbitrary ignore-style patterns.

git sparse-checkout init --cone
git sparse-checkout set src/app docs
git sparse-checkout list

A sparse-checkout is being configured.?The sparse specification is expressed as directories such as src/app and docs.

Change the selected directories with set

`set` replaces the current sparse specification with the supplied selection and updates the working tree accordingly. In cone mode, each argument is a directory. Treat it as a deliberate scope change: inspect the resulting list and working tree before continuing work.

git sparse-checkout set --cone src/app docs
git sparse-checkout list

A sparse-checkout is being configured.?The working tree is updated to match the new sparse specification.

Add to an existing cone selection

`add` expands the current sparse specification instead of replacing it. In cone mode, directory arguments add those directory subtrees to the selected set.

git sparse-checkout add src/lib
git sparse-checkout list

A sparse-checkout is being configured.?The previous sparse directories remain selected and src/lib is added.

Inspect the sparse specification with list

`list` reports the sparse specification. In cone mode it reports the selected directories; in non-cone mode it reports the patterns. This is useful evidence before or after changing the selection.

git sparse-checkout list

A sparse-checkout is being configured.?The current sparse directories or patterns are visible for inspection.

Non-cone mode: use gitignore-style patterns

Non-cone mode allows arbitrary gitignore-style patterns rather than only directory selections. This is useful when the desired subset cannot be expressed naturally as whole directory cones, but it has different semantics and can be more complex to reason about.

git sparse-checkout set --no-cone 'src/**/*.txt' 'docs/*.md'
git sparse-checkout list

A sparse-checkout is being configured.?The sparse specification contains patterns rather than only directory names.

Supply patterns through standard input

`set` and the sparse-checkout command support `--stdin` for supplying patterns as input. This can make a scripted or generated specification easier to pass without relying on shell argument quoting for every pattern.

git sparse-checkout set --no-cone --stdin <<'EOF'
src/app/
docs/
EOF

A sparse-checkout is being configured.?The supplied patterns become the sparse specification.

Reapply when the working tree and specification diverge

The sparse specification and the files actually present can temporarily diverge. For example, a tracked file outside the specification can be written into the working tree. `reapply` asks Git to restore the working tree and index to the sparse-checkout rules without changing the commit history.

git sparse-checkout reapply

A sparse-checkout is being configured.?The working tree is brought back in line with the current sparse specification.

Sparse index is an optional optimization

`--sparse-index` can be used with the sparse-checkout commands that support it to make the index sparse as well as the working tree. This can reduce index work for large repositories, but it is an implementation optimization rather than a different definition of which paths are selected.

git sparse-checkout init --cone --sparse-index
git sparse-checkout set --cone --sparse-index src/app
git sparse-checkout reapply --sparse-index

A sparse-checkout is being configured.?The index can use sparse directory entries while the sparse working-tree selection remains in force.

Disable sparse-checkout to restore the full working tree

`disable` turns off sparse-checkout and restores the working tree to include all tracked files. It does not delete commits or untrack files. Use it when the repository should return to an ordinary full working tree.

git sparse-checkout disable

A sparse-checkout is being configured.?Tracked files are populated again and sparse-checkout is disabled.

Sparse-checkout is not partial clone

Sparse-checkout controls the populated working-tree subset. A partial clone controls which repository objects, especially blobs, are initially available locally. The two features can be combined, but they solve different problems. Do not teach sparse-checkout as a way to remove Git history or as a network transfer filter.

A sparse-checkout is being configured.?The learner can reason separately about populated paths and repository object availability.

A disciplined sparse-checkout workflow

Start by deciding whether whole directories fit the task. Prefer cone mode for directory-oriented work. Use non-cone mode only when arbitrary patterns are genuinely required. Inspect the specification with `list`, use `reapply` when state has drifted, and use `disable` when returning to a full checkout. Treat sparse-checkout as a working-tree scope mechanism, not as deletion or history rewriting.

git sparse-checkout list
git sparse-checkout set --cone src/app docs
git sparse-checkout list
# If the working tree has drifted:
git sparse-checkout reapply
# When the sparse scope is no longer needed:
git sparse-checkout disable

What `git sparse-checkout` does not own

This lesson does not replace `git worktree`: worktrees provide multiple working directories with separate checkout state. It does not replace `.gitignore`: ignore rules govern untracked-file discovery rather than which tracked files are populated. It does not replace partial clone or `git clone --filter`: those concern object transfer and availability. It also does not rewrite commits or remove paths from history.

Practice what you learned

Use the dedicated Git code-completion exercise for this lesson.

Official source boundary

This lesson uses the official Git sparse-checkout documentation for command semantics and the official Git glossary/revision documentation where needed for terminology. No third-party documentation is used for Git command semantics.