Why Shallow Clones Break Your Changelog

A release job that generates a changelog from git tags starts failing with fatal: No names found, cannot describe anything, right after someone "optimized" the pipeline by adding --depth=1 to the checkout step. The build got noticeably faster. It also stopped being able to see its own history.

--depth=1 tells git to fetch only the most recent commit — nothing before it, and by default, none of the tags that would let you find your way back through the project's history. For a build that just compiles and runs tests, that's often fine. For anything generating release notes, computing a version from git describe, or diffing against the last tag, it's a quiet, specific kind of broken.

Watching it fail

A repo with four commits and two tags:

git log --oneline
# 6917460 commit 4
# 52f9c24 commit 3
# c5c0884 commit 2
# 807fe23 commit 1
git tag
# v1.0.0
# v1.1.0

A shallow clone, the way a "fast checkout" CI step would do it:

git clone --depth=1 file:///path/to/repo ci-runner
cd ci-runner
git log --oneline
# 6917460 commit 4

One commit. That's the entire point of --depth=1 — it's doing exactly what it was asked to do. The problem shows up the moment anything downstream expects more than the tip:

git tag
# (nothing)
 
git describe --tags
# fatal: No names found, cannot describe anything.
 
git log --oneline v1.0.0..HEAD
# fatal: ambiguous argument 'v1.0.0..HEAD': unknown revision or path not in the working tree.

No tags came down with the shallow clone, so there's nothing for git describe to count commits from, and no v1.0.0 to diff against for a changelog. This is exactly what breaks a semantic-release-style pipeline, or any CHANGELOG.md generator that walks commits since the last tag — the history it needs to walk was never fetched in the first place.

The fix that isn't "remove --depth"

The instinct is to drop --depth=1 and go back to a full clone, and that does work — but it's also exactly the slowness the flag was added to avoid, especially on a repository with years of history and a lot of binary assets in old commits. A partial clone gets the speed back without losing what a full clone gives you:

git clone --filter=blob:none file:///path/to/repo ci-runner
cd ci-runner
git log --oneline
# 6917460 commit 4
# 52f9c24 commit 3
# c5c0884 commit 2
# 807fe23 commit 1
git tag
# v1.0.0
# v1.1.0
git describe --tags
# v1.1.0-1-g6917460
git log --oneline v1.0.0..HEAD
# 6917460 commit 4
# 52f9c24 commit 3
# c5c0884 commit 2

--filter=blob:none still fetches every commit and every tree — the full shape of the repository's history — and only defers downloading file contents (blobs) until something actually needs to read them, such as a checkout. git describe and git log walk commits and trees, not blobs, so they see the complete picture immediately. The clone stays fast for the same reason --depth=1 was fast — most of a large repo's bytes are usually in old blob content, not in commit metadata — but nothing about history or tags is missing anymore.

Two things worth knowing before you switch

• The server has to support it. GitHub, GitLab, and Bitbucket all support partial clone filters on their hosted git protocol. A bare local repo or an older self-hosted git server might not — if it doesn't, git silently falls back to a full clone rather than failing, so check for warning: filtering not recognized by server, ignoring in your CI logs if the speed gain doesn't show up.
• Checkout still needs the blobs eventually. The first time you check out a branch or read a file, git fetches the blobs it needs on demand. That's usually still faster than a full clone up front, but it's not free — for extremely large binary-heavy repos, pair it with a sparse checkout if you also don't need every file in the tree.

If your CI pipeline reaches for --depth=1 purely for checkout speed, and anything downstream touches tags, git describe, or commit ranges, swap it for --filter=blob:none instead. Same speedup, none of the missing history.