Deep Dive into Shallow Clone

Overview

Shallow clone speeds up cloning by limiting how much history is downloaded. It's useful for CI/CD, large repositories, and quick prototyping.

Basic Usage

--depth

# Only the latest commit
git clone --depth 1 https://github.com/user/repo.git

# Last 10 commits
git clone --depth 10 https://github.com/user/repo.git

Each --depth N downloads the N most recent commits and their file snapshots.

--shallow-since

# All commits since a date
git clone --shallow-since="2025-01-01" https://github.com/user/repo.git

# Combine with --depth
git clone --depth 100 --shallow-since="2025-01-01" https://github.com/user/repo.git

--shallow-exclude

# Exclude a specific tag and its ancestors
git clone --shallow-exclude="v1.0" https://github.com/user/repo.git

Use Case Comparison

Limitations

1. Incomplete History Access

# Commits beyond --depth are invisible
git log --oneline
# Only shallow history shown

2. Cannot Push

# Shallow clone can't push by default
git push origin main
# Error: failed to push some refs
# Need to unshallow first

3. Some Git Operations Restricted

git merge
git log --all   # Incomplete
git bisect      # Incomplete

Converting to Full Clone

# Fetch remaining history
git fetch --unshallow

# Or specify a depth
git fetch --depth=500

# Now a full clone

Combining with Partial Clone

# Shallow + blobless partial clone
git clone --depth 1 --filter=blob:none https://github.com/user/repo.git

# Blobs are fetched on demand
git checkout feature-branch  # Auto-downloads needed blobs

CI Best Practices

# GitHub Actions - shallow by default
- uses: actions/checkout@v4
  with:
    fetch-depth: 0  # Set to 0 for full history

# GitLab CI
variables:
  GIT_DEPTH: 1

Continue Learning

1. performance/partial-clone — Partial clone guide
2. performance/gc-repack-strategies — gc/repack strategies
3. performance/large-repo-optimization — Large repo optimization