git-sparse-checkout

Enable sparse checkout

$ git sparse-checkout init

$ git sparse-checkout disable

$ git sparse-checkout set [path/to/directory]

$ git sparse-checkout add [path/to/directory]

git sparse-checkout [options] subcommand [arguments]
Common subcommands and options include:
git sparse-checkout init
git sparse-checkout set [--cone | --no-cone] [...]
git sparse-checkout add [...]
git sparse-checkout list
git sparse-checkout disable
git sparse-checkout status
git sparse-checkout reapply

init
    Initializes sparse-checkout for the current repository, enabling it.

set ...
    Replaces the current set of sparse-checkout patterns with new ones. This will also enable sparse-checkout if it's disabled.

add ...
    Adds specified patterns to the existing set of sparse-checkout patterns.

list
    Displays all currently active sparse-checkout patterns.

disable
    Disables sparse-checkout, populating the entire working directory with all files.

status
    Shows whether sparse-checkout is enabled, its current mode (cone or path-based), and other relevant information.

reapply
    Reapplies the current sparse-checkout patterns to the working directory. Useful after merges or rebases.

--cone
    Forces cone mode for the operation, even if not the default. Cone mode is the recommended and default pattern matching strategy.

--no-cone
    Disables cone mode, reverting to the older path-based sparse-checkout mode which allows arbitrary patterns.

--set-indexes
    Ensures that the index contains entries for files excluded by sparse-checkout, allowing them to be tracked. This is usually the default.

--no-set-indexes
    Prevents the index from being populated with entries for files excluded by sparse-checkout, making the index also 'sparse'.

git sparse-checkout allows users to reduce the size of their working directory to a manageable subset of files, making it highly beneficial for large repositories or monorepos. Instead of checking out the entire repository history, it only populates the working tree with files matching specified patterns. This significantly improves performance for operations like git status, git add, and git commit, and reduces disk space usage.
The command manages these sparse-checkout patterns, which dictate which files are present in your local copy. It primarily operates in two modes: the older path-based mode, which uses arbitrary patterns, and the modern, recommended cone mode. Cone mode is the default and includes only files residing within specified directories and their immediate ancestors. Files outside these patterns are still part of the repository history but are simply not checked out into the working directory.

While git sparse-checkout is powerful, using non-cone mode patterns can be less performant and harder to manage; cone mode is highly recommended. It's important to note that not all Git commands fully respect sparse-checkout patterns in all scenarios. After complex history rewriting operations like git merge or git rebase, running git sparse-checkout reapply is often necessary to ensure the working directory correctly reflects the updated patterns and the sparse-checkout configuration.

Patterns define which files from the repository are materialized in your working directory. In cone mode, patterns are typically directory paths (e.g., 'src/projectA/'). Git then automatically includes all files within these specified directories. It also implicitly includes files in ancestor directories that contain other specified directories (e.g., if 'src/projectA/' is specified, files directly in 'src/' might be included if 'src/' also contains 'src/projectB/'). The older path-based mode, by contrast, allows more arbitrary glob patterns (e.g., 'src/projectA/*.c', 'docs/*.md'), which can be less efficient and harder to maintain consistently.

The fundamental concept of sparse checkout has existed in Git for a long time, initially managed by manually editing the .git/info/sparse-checkout file with path-based patterns. This older method often led to complexities and performance issues for very large repositories. The git sparse-checkout command itself was introduced with Git 2.25, alongside the highly significant 'cone mode' sparse checkout feature. Cone mode dramatically simplified pattern management and improved performance, eventually becoming the default and recommended sparse-checkout strategy in later Git versions.

git(1), git-config(1), git-read-tree(1), git-update-index(1), git-checkout(1)