Keep a Large Git Checkout Focused with Sparse Paths

You will finish with a Git working tree that contains the top-level files and the project directories you actually need, while the remaining tracked files stay in the index but are not materialised on disk. This guide uses Git 2.43.0, the version installed here as package git 1:2.43.0-1ubuntu7.3. Allow about ten minutes for a clean repository.

You need an existing Git checkout and a clean or deliberately saved working tree. The examples use src and docs as directory names. Replace them with directories that exist in your repository. Sparse checkout is experimental, and the selected paths affect how commands such as branch switching and git commit -a behave.

1. Confirm the Git version and save work

Run these ordinary, read-only checks from the repository root. No elevated privileges are needed:

$ git --version
git version 2.43.0
$ git status --short

An empty status is the simplest starting point. If status prints modified, deleted or untracked paths, commit them, stash them, or copy important untracked files somewhere safe before changing the sparse definition. Do not use sudo to work around a repository permission problem; fix the ownership or access issue separately.

2. Select directories in cone mode

For ordinary projects, use cone mode, which is the default. It takes directory names, not arbitrary shell patterns:

$ git sparse-checkout set src docs

This enables the sparse-checkout settings, writes the selection, and updates the working tree. Every tracked file below src/ and docs/ is included at any depth. Git also keeps files immediately below the repository root and immediately below each leading directory, so supporting files such as src/Makefile may appear even when you selected src/lib/. That parent-file behaviour is part of cone mode, not an accidental extra match.

The command can remove ignored files in directories that no longer have selected tracked or non-ignored untracked content. Review valuable ignored build output before changing the selection. Tracked files are not lost: they remain in Git, but their working-tree copies are removed.

Verify both the definition and the visible files:

$ git sparse-checkout list
src
docs
$ git status --short
$ find src docs -maxdepth 2 -type f | sort

The exact find output depends on the repository. The useful check is that selected paths are present and a known unselected directory is absent.

3. Add another directory without replacing the selection

Use add when you want to widen the current cone:

$ git sparse-checkout add tools
$ git sparse-checkout list
src
docs
tools

add must be used after sparse checkout is already enabled. If you use set tools instead, Git replaces the current selection with tools; it does not append to it. For a long list, newline-delimited input avoids shell quoting mistakes:

$ printf '%s\n' examples tests | git sparse-checkout add --stdin

Keep the input as directory names in cone mode. A shell glob such as * is not a harmless shortcut here. An unquoted glob can expand before Git sees it, and an accidental selection can remain unnoticed until a later branch switch or rebase.

4. Check which paths match before relying on them

The check-rules subcommand reads paths from standard input and prints the ones matched by the current rules. This is useful in scripts and when the cone's parent-file behaviour is surprising:

$ printf '%s\n' src/main.c docs/guide.txt vendor/lib.c | git sparse-checkout check-rules
src/main.c
docs/guide.txt

Only matched input is printed. This does not inspect file contents or prove that a path exists in the current commit; it checks the sparse rules. Use git ls-tree when you need to establish what is tracked.

For machine-readable paths, add -z to make input and output NUL-terminated and avoid quoting ambiguities:

$ printf 'src/main.c\0vendor/lib.c\0' | git sparse-checkout check-rules -z | tr '\0' '\n'
src/main.c

5. Reapply the rules after a merge or conflict

Some operations materialise paths outside the selected cone, especially when showing conflicts. External tools can also create files in places the sparse rules exclude. Once you have resolved conflicts or saved any changes, ask Git to enforce the existing definition again:

$ git sparse-checkout reapply
$ git sparse-checkout list
src
docs
tools

reapply does not choose new directories. It reapplies the current rules. If a modified or conflicted file cannot be removed, Git may leave it in place; resolve, undo or commit that change before trying again. Check git status rather than assuming the filesystem is already sparse.

6. Understand non-cone mode before using it

--no-cone interprets the input as Git-ignore-style patterns, which can select finer-grained paths:

$ git sparse-checkout set --no-cone '/*' '!unwanted'

This example includes everything and excludes a top-level path named unwanted. Quote patterns so the shell does not expand them first. The pattern syntax is closer to .gitignore than to Git pathspecs, but the purpose is reversed: sparse patterns usually describe what to include. That mismatch is a common source of mistakes.

The installed manual recommends against non-cone mode. It can scale poorly with many patterns, does not work with some features such as the sparse index, and has no remove subcommand for safely undoing an accidental addition. Prefer cone mode unless the directory model genuinely cannot express the checkout.

7. Restore the complete working tree

When you no longer need the reduced checkout, restore every tracked file and disable sparse checkout:

$ git sparse-checkout disable
$ git status --short
$ git sparse-checkout list
fatal: this worktree is not sparse

The final diagnostic wording can vary, but the important result is that disable succeeds and the previously absent tracked files are present again. This is the normal undo operation. It does not remove commits or rewrite history.

If you enabled a sparse index and an older external tool cannot understand it, rewrite the index in its normal form with:

$ git sparse-checkout init --no-sparse-index

Git 2.43 defaults to a non-sparse index, so most users do not need this command. The init subcommand is deprecated; use set for new sparse checkouts. This locally installed version does not document the newer clean subcommand, so do not copy that command into a Git 2.43 workflow.