Git shallow clone: what it is, when to use it, and how

Cloning a repository with git clone typically pulls the entire commit history. But what if you don’t need the whole thing? That’s where shallow clones come in. In this article, we’ll explain what a shallow clone is, how it works, and when it makes sense to use it — with copy-paste-ready examples.

What is a shallow clone in Git?

A shallow clone is a Git clone that pulls only part of a repository’s history instead of everything from the beginning. This significantly reduces the download size and time. It’s especially useful when:

• You don’t need the full commit history
• You want faster setup for CI/CD pipelines
• You’re working with large repositories

Shallow clone vs normal clone

Feature Normal Clone Shallow Clone Fetches entire history Yes No (limited commits) Clone speed Slower Faster Git operations (rebase, bisect) Fully supported Some limitations Ideal for CI/CD Not optimal Yes

How to perform a shallow clone

Clone only the most recent commit

git clone --depth=1 https://github.com/owner/repo.git

Clone a specific branch with limited history

git clone --depth=1 --branch main --single-branch https://github.com/owner/repo.git

Clone commits since a specific date

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

You can also use --filter=blob:none with partial clones if you want to skip large file downloads entirely.

Can you unshallow a shallow clone?

Yes. If you later decide you need full history:

git fetch --unshallow

This pulls the missing commits and converts your shallow clone into a full one.

When should you use a shallow clone?

Use a shallow clone when:

• You only need the latest version of the code
• You’re running CI pipelines and want faster builds
• You’re inspecting or testing code without needing full history

Avoid shallow clones when:

• You need to perform git bisect, git rebase, or merge operations
• You’re contributing changes and need access to commit history
• You’re writing tooling that depends on the full repository context

Common issues with shallow clones

Git operations may fail

Some commands assume full history and will throw errors in shallow clones:

• git merge-base
• git rebase
• git bisect

Fix: Run git fetch --unshallow or avoid shallow clone in those contexts.

Shallow clones may break monorepo tooling

Tools like Lerna or Nx may assume full access to the repo’s commit history for dependency graphs or affected packages. Test with your specific toolchain.

Conclusion

Shallow clones are a great way to speed up development workflows, especially in CI or when working with large repos. Just be aware of the trade-offs — and you can always unshallow later if needed.

FAQs