Git Sparse Checkout

Git sparse checkout lets you keep only selected directories or files in your working tree while the repository still tracks the complete project. It is useful for large monorepos when you work on one application, service, or documentation area and do not need every checked-out file.

Sparse checkout changes what appears in your working directory. It does not delete branches or rewrite repository history.

When to Use Sparse Checkout

• You work in a monorepo but only maintain one service.
• A repository contains large generated, media, or platform-specific directories.
• You want a smaller working tree for faster navigation and some Git operations.
• Your build or editor should focus on a limited part of the project.

Important: Sparse checkout alone does not prevent Git from downloading repository objects. Combine it with partial clone when you also want to delay downloading file contents.

Check Your Git Version

Use a current Git release because sparse-checkout behavior and sparse-index support have improved over time.

Command:

# Display the installed Git version
git --version

Output:

git version 2.51.0

Clone a Repository for Sparse Checkout

The simplest workflow starts with git clone --sparse. The --filter=blob:none option creates a partial clone and downloads file contents only when Git needs them.

Example:

# Clone without checking out every directory or downloading every blob
git clone --filter=blob:none --sparse https://github.com/example/commerce.git

# Move into the cloned repository
cd commerce

Output:

Cloning into 'commerce'...
remote: Enumerating objects: 842, done.
Receiving objects: 100% (842/842), done.

After a sparse clone, Git initially includes files at the repository root. Select the directories you need in the next step.

Select Directories in Cone Mode

Cone mode accepts directory names and is the recommended mode for most projects. It is easier to understand and performs better than arbitrary pattern matching.

Suppose the repository contains these paths:

apps/store
apps/admin
packages/ui
packages/payments
docs

Example:

# Check out the store application and its shared UI package
git sparse-checkout set apps/store packages/ui

# Show the active sparse directory rules
git sparse-checkout list

Output:

apps/store
packages/ui

The working tree now contains the selected directories, their parent directories, and files Git includes at the repository root. Git still understands paths outside the sparse area.

Enable Sparse Checkout in an Existing Clone

If you already cloned the full repository, initialize sparse checkout and then set the required directories.

Example:

# Enable recommended directory-based matching and a compact sparse index
git sparse-checkout init --cone --sparse-index

# Keep only the API service and documentation
git sparse-checkout set services/api docs

Output:

Working tree updated to include:
services/api
docs

A sparse index can reduce index work in a very large repository. If an older external Git tool cannot read it correctly, run git sparse-checkout init --no-sparse-index to return to a full index while keeping the sparse working tree.

Add Another Directory

Use add when you want to expand the current selection without repeating the existing paths.

Example:

# Add the payments package to the current sparse selection
git sparse-checkout add packages/payments

# Confirm all selected directories
git sparse-checkout list

Output:

docs
packages/payments
services/api

Replace the Current Selection

The set command replaces the existing sparse specification. Use it when your work moves to another part of the repository.

Example:

# Replace every previous selection with the admin application
git sparse-checkout set apps/admin

Output:

Working tree updated to include:
apps/admin

Select Individual Files with Non-Cone Mode

Non-cone mode accepts gitignore-style patterns and can include individual files. It is more flexible, but it is harder to maintain and may perform worse on a large repository. Prefer cone mode unless directory selection cannot express your requirement.

Example:

# Use pattern mode to include one file and the documentation tree
git sparse-checkout set --no-cone "/README.md" "/docs/**"

Tip: Quote non-cone patterns so your shell does not expand wildcard characters before Git receives them.

Restore Files After Conflicts or Manual Changes

Some Git operations or conflicting modifications can leave paths outside the sparse specification in the working tree. Reapply the rules after you protect or commit any valuable work.

Command:

# Reapply the current sparse rules to the working tree
git sparse-checkout reapply

Disable Sparse Checkout

Disable the feature when you need the complete working tree again. Git restores all tracked paths for the current revision.

Command:

# Return to a normal full checkout
git sparse-checkout disable

Output:

Working tree restored to a full checkout.

Important Behavior

• Branch switching, merging, and rebasing continue to operate on the repository, while Git limits working-tree updates to the sparse specification.
• git status does not treat intentionally missing paths as deleted files.
• Submodules have their own working trees and require separate initialization.
• Build tools may still fail if a selected directory depends on files outside the sparse area.
• Use git sparse-checkout list before changing rules so you know the current selection.

Recommended Workflow

1. Use partial clone with --filter=blob:none when network and disk usage matter.
2. Choose cone mode and directory paths for predictable behavior.
3. Enable --sparse-index for a large monorepo after confirming tool compatibility.
4. Add all build-time dependencies to the sparse selection.
5. Commit or stash changes before replacing or disabling sparse rules.

Conclusion

Git sparse checkout reduces a large working tree to the paths you need. Start with cone mode, use set and add to manage directories, and combine sparse checkout with partial clone when you also want fewer downloaded blobs. Clear selections and visible command output make the workflow safe and easy to maintain.