Introduction

A shallow clone (git clone --depth 1) downloads only the latest commit (or a specified number of recent commits) without the full repository history. This speeds up cloning for large repositories but prevents operations that need history: git log, git blame, git bisect, and generating changelogs. Converting a shallow clone to a full clone retrieves the missing history from the remote.

The Quick Fix

git fetch --unshallow

This single command fetches all missing commits, tags, and branches from the remote, converting the shallow clone into a full clone with complete history.

Verify the conversion:

git rev-parse --is-shallow-repository
# false

If the output is false, the repository now has full history.

What --unshallow Actually Does

A shallow clone stores a marker file at .git/shallow listing the commit SHAs where history was cut off. git fetch --unshallow does three things:

1. Fetches all commits from the remote that are ancestors of the shallow boundary commits
2. Fetches all commits on all remote branches (not just the checked-out branch)
3. Removes the .git/shallow file

1# Before --unshallow
2cat .git/shallow
3# a1b2c3d4e5f6...  (the boundary commit SHA)
4
5git log --oneline | wc -l
6# 1 (or however many commits --depth specified)
7
8# After --unshallow
9cat .git/shallow
10# cat: .git/shallow: No such file or directory
11
12git log --oneline | wc -l
13# 4523 (full history)

Fetching All Branches and Tags

--unshallow fetches history for the current branch's remote. To ensure you have everything:

git fetch --unshallow
git fetch --all --tags

--all fetches from all configured remotes (useful if you have multiple remotes like origin and upstream). --tags ensures annotated tags are downloaded.

Deepening Incrementally Instead of Full Fetch

If you do not need the entire history but want more than the shallow clone provided:

1# Deepen by 50 more commits
2git fetch --deepen=50
3
4# Or set an absolute depth
5git fetch --depth=100
6
7# Fetch history up to a specific date
8git fetch --shallow-since="2024-01-01"
9
10# Fetch history excluding a specific commit
11git fetch --shallow-exclude=v1.0.0

Incremental deepening is useful when the full history is enormous (hundreds of thousands of commits) and you only need history back to a certain point.

Handling CI/CD Shallow Clones

Most CI systems shallow-clone by default for speed. If your build step needs full history (for versioning, changelogs, or git describe), you need to either configure the CI to do a full clone or deepen after checkout.

GitHub Actions

- uses: actions/checkout@v4
  with:
    fetch-depth: 0  # 0 means full clone

GitLab CI

1variables:
2  GIT_DEPTH: 0  # Full clone
3
4# Or deepen in a script step:
5script:
6  - git fetch --unshallow || true

Jenkins

1checkout([
2    $class: 'GitSCM',
3    extensions: [[$class: 'CloneOption', shallow: false]]
4])

Bitbucket Pipelines

clone:
  depth: full

When the Remote Does Not Support --unshallow

Some Git hosting configurations or older Git versions may not support --unshallow. The fallback is to fetch with a very large depth:

git fetch --depth=2147483647

This requests effectively unlimited history, achieving the same result as --unshallow.

If even that fails, re-clone from scratch:

cd ..
mv my-repo my-repo-shallow
git clone https://github.com/user/repo.git my-repo

Checking If a Repository Is Shallow

1# Boolean check
2git rev-parse --is-shallow-repository
3# true or false
4
5# See how many commits are available
6git rev-list --count HEAD
7
8# Check if .git/shallow exists
9test -f .git/shallow && echo "Shallow" || echo "Full"

Shallow Clone vs Partial Clone

Git 2.22+ introduced partial clones, which are different from shallow clones:

1# Shallow clone — limits by commit count
2git clone --depth 1 https://github.com/user/repo.git
3
4# Partial clone — skips large blobs, fetches them on demand
5git clone --filter=blob:none https://github.com/user/repo.git

Partial clones keep full commit history but skip file contents until needed. This gives you git log, git blame, and git bisect without downloading large binary files upfront. For most CI and development use cases, partial clones are a better choice than shallow clones.

Common Pitfalls

• git log shows only recent commits: This is the most visible symptom of a shallow clone. Run git fetch --unshallow to get full history.
• git push fails from a shallow clone: Pushing from a shallow clone can fail if the remote requires history that the local clone does not have. Unshallow before pushing.
• git submodule with shallow clones: Submodules can be independently shallow. Use git submodule update --init --recursive --depth=0 (Git 2.10+) or --no-shallow-submodules to ensure submodules get full history.
• Disk space after unshallowing: A full clone of a large repository can be significantly larger. For the Linux kernel, a shallow clone is about 200 MB while a full clone is over 4 GB.
• Network bandwidth: --unshallow downloads the entire missing history in one fetch. On slow connections, consider --deepen incrementally or use --shallow-since to limit how far back you go.

Summary

• Run git fetch --unshallow to convert a shallow clone to a full clone
• Verify with git rev-parse --is-shallow-repository (should return false)
• Use git fetch --all --tags to ensure all branches and tags are downloaded
• Configure CI systems with fetch-depth: 0 to avoid shallow clones when full history is needed
• Use --deepen or --shallow-since for partial history expansion without downloading everything
• Consider partial clones (--filter=blob:none) as a modern alternative to shallow clones