Deep Dive into Shallow Clone

What you will learn

• Understand the core purpose of Deep Dive into Shallow Clone
• Master the basic usage and common options of Deep Dive into Shallow Clone
• Understand how git clone --depth and --shallow-since work, their use cases, limitations, and how to convert a shallow clone to a full one.
• Understand key concepts: Overview
• Know when to use this feature and when to avoid it

Start with a problem

Your Git repository keeps growing, clones are getting slower, and everyday operations are starting to feel sluggish. You want to know what optimization techniques are available and which ones fit your project.

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

Try it yourself

1. Practice the shallow-clone-deep command in a test repository and observe state changes before and after
2. Experiment with different options and compare the output differences
3. Simulate a real scenario where you would need to use this, and walk through the full process

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

Further reading

Keep going on the same topic:

• Partial Clone: On-Demand Git Object Fetching
• Scalar Git Deep Dive