Git Sparse Checkout Guide

In this tutorial, you'll learn about Git Sparse Checkout Guide. We cover key concepts, practical examples, and best practices.

Git sparse checkout lets you clone and work with only a subset of directories in a repository, dramatically reducing disk usage and checkout time for large projects.

In this tutorial, you'll learn Git sparse checkout — how to configure it for partial clones, manage sparse checkout patterns, and use it effectively with monorepos and large repositories. Sparse checkout is essential when working with monorepos containing dozens of projects or when you only need specific parts of a large codebase. By the end, you'll set up a sparse checkout workflow for a monorepo.

Real-world use: DodaTech's monorepo contains Doda Browser, DodaZIP, and Durga Antivirus Pro. Each team uses sparse checkout to work only on their product's directory. CI pipelines use sparse checkout to clone only the changed project's dependencies.

flowchart TD
  A[git clone --sparse] --> B[Minimal checkout]
  B --> C[Only top-level files]
  C --> D[git sparse-checkout set]
  D --> E[Specify directories]
  E --> F[git sparse-checkout add]
  F --> G[Add more patterns]
  G --> H[git sparse-checkout reapply]
  H --> I[Updated working tree]
  I --> J[Only requested dirs]

Enabling Sparse Checkout

Start with a partial clone and enable sparse checkout.

# Clone without checking out files
git clone --no-checkout https://github.com/dodatech/monorepo.git
cd monorepo

# Enable sparse checkout
git sparse-checkout init --cone

# Specify which directories to check out
git sparse-checkout set browser/ shared-libs/

Expected output:

$ ls
browser/  shared-libs/

# Only these directories appear — not the 20 other directories in the repo
$ du -sh .
48M     .
# Full clone would be 2.3GB

One-Command Sparse Clone

Git 2.25+ supports cloning with sparse checkout in a single command.

# Clone with sparse checkout enabled from the start
git clone --sparse https://github.com/dodatech/monorepo.git
cd monorepo
git sparse-checkout set browser/ shared-libs/

# Even shorter: clone + sparse in one command
git clone --filter=blob:none --sparse \
  https://github.com/dodatech/monorepo.git

The --filter=blob:none option skips downloading file contents for files outside your sparse checkout, saving bandwidth and disk space.

Managing Sparse Checkout Patterns

Add, remove, and list sparse checkout directories.

# List current sparse directories
git sparse-checkout list
# Expected:
# browser/
# shared-libs/

# Add additional directories
git sparse-checkout add antivirus/ docs/

# Verify
git sparse-checkout list
# Expected:
# browser/
# shared-libs/
# antivirus/
# docs/

# Reset to only specific directories
git sparse-checkout set browser/

# Disable sparse checkout (checkout everything)
git sparse-checkout disable

Cone Mode vs Full Mode

Git offers two modes for sparse checkout patterns.

# Cone mode (recommended) — simple directory patterns
git sparse-checkout init --cone
git sparse-checkout set browser/ antivirus/

# Full mode — full gitignore-style patterns
git sparse-checkout init --no-cone
git sparse-checkout set "src/*" "!src/tests/" "docs/*.md"

Sparse Checkout with Partial Clone

Combine with partial clone for maximum efficiency.

# Partial clone: only download metadata, not file contents
git clone --filter=blob:none --sparse \
  https://github.com/dodatech/monorepo.git

# Blobless partial clone: fetch files on demand
git clone --filter=blob:none --sparse \
  https://github.com/dodatech/monorepo.git

# Tree-less partial clone: even more minimal
git clone --filter=tree:0 --sparse \
  https://github.com/dodatech/monorepo.git

Monitor disk usage:

$ du -sh .git objects/
# Partial sparse clone: 120MB
# Full clone: 2.1GB

# Check how many blobs are missing
git rev-list --objects --all | wc -l
# Expected: far fewer than a full clone

Sparse Checkout in CI/CD

Reduce CI pipeline time by cloning only what you need.

# .github/workflows/ci.yml — fast CI with sparse checkout
name: CI

on: [pull_request]

jobs:
  test-browser:
    runs-on: ubuntu-latest
    steps:
      - name: Sparse checkout
        uses: actions/checkout@v4
        with:
          sparse-checkout: |
            browser/
            shared-libs/
            package.json
          sparse-checkout-cone-mode: true

      - name: Install and test
        run: |
          cd browser
          npm ci
          npm test

  test-antivirus:
    runs-on: ubuntu-latest
    steps:
      - name: Sparse checkout
        uses: actions/checkout@v4
        with:
          sparse-checkout: |
            antivirus/
            shared-libs/
          sparse-checkout-cone-mode: true

      - name: Install and test
        run: |
          cd antivirus
          npm ci
          npm test

Expected CI speedup:

Clone time: 45s → 8s (full clone → sparse checkout)
Disk usage: 2.1GB → 85MB

Working with Sparse Checkout

Understand how Git commands behave in a sparse checkout.

# Status only shows changes in checked-out files
git status
# Expected: only files in browser/ and shared-libs/

# Diff only shows checked-out files
git diff

# Add works as normal (only within checked-out files)
git add browser/src/new-feature.js

# Fetch still works for the whole repository
git fetch origin main

# Merge or rebase only affects checked-out files
git pull origin main

Checking Out Specific Files

In cone mode, you can still check out specific files using patterns.

# Enable full patterns temporarily
git sparse-checkout init --no-cone

# Check out specific files
git sparse-checkout set "README.md" "package.json" "docs/guide.md"

# Add individual files
git sparse-checkout add "antivirus/src/main.py"

Common Errors

1. git sparse-checkout set fails with "not a sparse checkout" — Run git sparse-checkout init --cone first to enable sparse checkout mode before setting patterns.
2. Files unexpectedly missing after git pull — If new directories were added to the remote that match your patterns, they appear automatically. If not, run git sparse-checkout reapply.
3. git add stages files outside sparse checkout — By default, Git ignores files outside the sparse checkout in commands like git add and git status. Use git sparse-checkout reapply if you see unexpected files.
4. Slow sparse checkout in non-cone mode — Full gitignore-style patterns are much slower than cone mode. Use cone mode unless you need the pattern flexibility.
5. --filter=blob:none not working — Requires Git 2.19+ and server support (most major Git hosts support it). Check server compatibility before relying on partial clone features.

Practice Questions

Challenge

Create a monorepo with multiple projects and practice sparse checkout. Initialize a repo with three directories (project-a, project-b, shared). Add 100 files in each directory. Clone it with --sparse and measure clone time and disk usage. Practice switching between different sparse sets. Measure the time for git status in each configuration. Document the disk usage savings.

Real-World Task

The DodaTech monorepo contains all three products — Doda Browser, DodaZIP, and Durga Antivirus Pro — in a single repository totaling 4.5GB. Configure sparse checkout for: the browser team (checkout only browser/ and shared-libs/), the antivirus team (checkout antivirus/, shared-libs/, and signatures/), and the CI pipeline (checkout only the changed product's directory). Measure the clone time reduction and disk savings for each configuration.

Previous: Monorepos with Git | Related: Git for Teams | Related: Git LFS

Built by the developers of Doda Browser, DodaZIP, and Durga Antivirus Pro.