Git Shallow Sparse

Git Shallow & Sparse Clones

Trigger: Use when cloning large repos, working in CI with limited history, or only needing part of a monorepo.

Clone Types for Large Repos

Shallow Clone

# Last commit only
git clone --depth 1 https://github.com/owner/repo.git

# Last N commits
git clone --depth 50 https://github.com/owner/repo.git

# Shallow since a date
git clone --shallow-since="2024-01-01" https://github.com/owner/repo.git

# Shallow with tags
git clone --depth 1 --no-single-branch https://github.com/owner/repo.git

# Un-shallow (fetch the rest)
git fetch --unshallow

Sparse Checkout

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

# Enable sparse checkout
git sparse-checkout init --cone     # Cone mode (fast)
git sparse-checkout set src/api tests/
git checkout main

# Add more directories
git sparse-checkout add docs/

# List sparse patterns
git sparse-checkout list

# Disable sparse checkout
git sparse-checkout disable

Sparse Checkout with Shallow

# Combined — fastest possible clone for CI
git clone --depth 1 --filter=blob:none --sparse \
  https://github.com/owner/repo.git
cd repo
git sparse-checkout set src/my-package/

Blobless & Treeless Clones

# Blobless — full commit/tree history, no file contents
git clone --filter=blob:none https://github.com/owner/repo.git
# Files are downloaded on-demand during checkout

# Treeless — minimal (no trees either)
git clone --filter=tree:0 https://github.com/owner/repo.git
# Needs --depth or partial clone protocol

# Partial clone with fetch
git clone --filter=blob:none https://github.com/owner/repo.git
git checkout main                        # Downloads files for HEAD
git diff HEAD~1 HEAD -- src/file.ts      # Downloads blob for that commit

CI Optimizations

# Fastest CI checkout
steps:
  - uses: actions/checkout@v4
    with:
      fetch-depth: 1           # Shallow — no history
      sparse-checkout: |       # Only needed dirs
        src/
        tests/
        Cargo.toml
      sparse-checkout-cone-mode: true

Working with Partial Clones

# Git-aware operations still work
git log --oneline -5           # History is local (blobless mode)
git diff HEAD~1                # Downloads missing blobs automatically

# Force download all blobs
git fetch --refetch

# Check what's missing
git rev-list --objects --all --count 2>/dev/null
git cat-file --batch-check --batch-all-objects | wc -l

Pitfalls

• Shallow push: git push from shallow clone fails if remote doesn't have the base — use --depth with matching remote
• Sparse + tags: git fetch --tags in cone mode fetches tags but not files outside cone
• Blobless clone requires protocol v2: git config --global protocol.version 2
• CI with shallow: Some actions (like CodeQL) need full history — override with fetch-depth: 0
• Partial clone + LFS: LFS files still download as needed — no extra benefit

Verification

git rev-list --count HEAD              # Commits in local history
git ls-files | wc -l                   # Checked-out files
git rev-parse --is-shallow-repository  # true/false
git sparse-checkout list               # Active sparse patterns