How to shallow clone in Git
Łukasz Holeczek
Follow Łukasz Holeczek on GitHub
Connect with Łukasz Holeczek on LinkedIn
Follow Łukasz Holeczek on X (Twitter)
Shallow cloning downloads only recent commits instead of entire repository history, dramatically reducing clone time and disk space for large repositories. As the creator of CoreUI, a widely used open-source UI library, I’ve optimized Git workflows for large codebases throughout my 25 years of development experience. The most practical approach is using git clone –depth parameter to limit history depth, ideal for CI/CD pipelines and quick repository access. This method reduces network bandwidth consumption, speeds up clones by up to 10x for large repositories, and minimizes local storage requirements.
Use git clone –depth to download only recent commits without full repository history for faster cloning.
# Regular clone (downloads entire history)
git clone https://github.com/user/repo.git
# Downloads all commits, all branches, all tags
# Shallow clone with depth 1 (only latest commit)
git clone --depth 1 https://github.com/user/repo.git
# Downloads only the most recent commit
# Shallow clone with depth 10
git clone --depth 10 https://github.com/user/repo.git
# Downloads last 10 commits
# Shallow clone specific branch
git clone --depth 1 --branch main https://github.com/user/repo.git
# Only clones main branch with latest commit
# Shallow clone with single branch
git clone --depth 1 --single-branch https://github.com/user/repo.git
# Clones default branch only, no other branches
Comparison of clone types:
# Full clone
git clone https://github.com/torvalds/linux.git
# Size: ~3.5GB, Time: ~15 minutes
# All history, all branches, all tags
# Shallow clone depth 1
git clone --depth 1 https://github.com/torvalds/linux.git
# Size: ~180MB, Time: ~1 minute
# Only latest commit on default branch
# Single branch shallow clone
git clone --depth 1 --single-branch --branch master \
https://github.com/torvalds/linux.git
# Size: ~180MB, Time: ~1 minute
# Only master branch, latest commit
Working with shallow clones:
# Check if repository is shallow
git rev-parse --is-shallow-repository
# Output: true (shallow) or false (full)
# View shallow file
cat .git/shallow
# Contains SHA-1 of shallow commits
# Fetch more history
git fetch --depth 50
# Deepens history to 50 commits
# Fetch all history (convert to full clone)
git fetch --unshallow
# Downloads complete history
# Deepen by specific number of commits
git fetch --deepen 20
# Adds 20 more commits to history
Shallow clone use cases:
# CI/CD pipeline - only need latest code
git clone --depth 1 --single-branch https://github.com/user/repo.git
cd repo
npm install
npm test
npm run build
# Quick code review - specific branch
git clone --depth 1 --branch feature-x https://github.com/user/repo.git
cd repo
# Review code changes
# Build Docker image - minimize layer size
FROM node:20
WORKDIR /app
RUN git clone --depth 1 https://github.com/user/repo.git .
RUN npm install && npm run build
# Download specific tag
git clone --depth 1 --branch v2.0.0 https://github.com/user/repo.git
# Downloads specific version only
Limitations of shallow clones:
# Cannot push from shallow clone
git clone --depth 1 https://github.com/user/repo.git
cd repo
# Make changes
git add .
git commit -m "Update"
git push
# Error: shallow update not allowed
# Solution: Unshallow first
git fetch --unshallow
git push
# Now works
# Cannot clone shallow repository
git clone --depth 1 https://github.com/user/repo.git original
cd original
# Try to clone from local shallow repo
git clone original copy
# Error: --depth is only supported for remote repositories
# Limited history access
git clone --depth 1 https://github.com/user/repo.git
cd repo
git log
# Only shows 1 commit
git blame file.js
# Limited blame information
git log --all
# Only shows commits in shallow history
Converting between shallow and full:
# Shallow to full
git clone --depth 1 https://github.com/user/repo.git
cd repo
git fetch --unshallow
# Now have full history
# Fetch specific depth
git fetch --depth 100
# Have 100 commits of history
# Fetch all branches after shallow clone
git remote set-branches origin '*'
git fetch --depth 1
# Fetches all branches with depth 1
# Full clone specific branch later
git clone --depth 1 --single-branch https://github.com/user/repo.git
cd repo
git remote set-branches --add origin develop
git fetch origin develop --depth 1
# Now have main and develop branches
Optimizing CI/CD with shallow clones:
# GitHub Actions
name: CI
on: [push]
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 1 # Shallow clone
- name: Build
run: npm install && npm run build
- name: Test
run: npm test
# GitLab CI
build:
variables:
GIT_DEPTH: 1 # Shallow clone
script:
- npm install
- npm run build
- npm test
# Manual shallow clone in CI
git clone --depth 1 --single-branch --branch $BRANCH_NAME $REPO_URL
cd repo
npm install
npm test
Bandwidth and storage savings:
# Large repository example (React)
# Full clone
git clone https://github.com/facebook/react.git
# Size: ~270MB, Time: ~30 seconds
# Shallow clone
git clone --depth 1 https://github.com/facebook/react.git
# Size: ~15MB, Time: ~3 seconds
# 95% size reduction, 90% time reduction
# Very large repository (Linux kernel)
# Full clone: 3.5GB, 15+ minutes
# Shallow clone: 180MB, 1 minute
# 95% size reduction, 93% time reduction
Best practices for shallow clones:
# For CI/CD - always use depth 1
git clone --depth 1 --single-branch https://github.com/user/repo.git
# For development - use full clone
git clone https://github.com/user/repo.git
# For quick testing - use shallow with specific branch
git clone --depth 1 --branch feature-x https://github.com/user/repo.git
# For releases - clone specific tag
git clone --depth 1 --branch v1.0.0 https://github.com/user/repo.git
# For Docker builds - minimize image size
RUN git clone --depth 1 --single-branch https://github.com/user/repo.git
Here the –depth parameter limits commit history to specified number of commits. The –single-branch clones only specified branch without other branches. The .git/shallow file marks repository as shallow clone. The git fetch –unshallow converts shallow clone to full repository with complete history. The –deepen parameter incrementally adds more history to shallow clone. Shallow clones reduce bandwidth and storage but limit history operations. The git rev-parse –is-shallow-repository checks shallow status.
Best Practice Note:
This is the shallow cloning strategy we use in CoreUI CI/CD pipelines to minimize build times and bandwidth consumption for automated deployments. Use shallow clones exclusively for CI/CD and automated builds where full history is unnecessary, avoid shallow clones for development environments where git blame and history analysis are needed, leverage –single-branch with –depth 1 for Docker image builds to minimize layer sizes, and document shallow clone limitations for team members unfamiliar with partial repository cloning.
