Introduction

Git shallow clones (--depth 1) download only the latest commit to save time and bandwidth. However, this strips tags, branch history, and commit metadata that many build tools rely on for version detection:

bash
git clone --depth 1 https://github.com/org/repo.git
cd repo
git describe --tags
# fatal: No names found, cannot describe anything.

Build tools that use git describe, git tag, or commit counting for version strings fail in CI/CD pipelines.

Symptoms

  • git describe --tags fails with "No names found"
  • Build version shows "0.0.0-unknown" instead of the actual version
  • git tag returns empty output
  • Build tools cannot determine the version from git metadata
  • Semantic versioning plugins fail to find version tags

Common Causes

  • --depth 1 clone does not fetch tags by default
  • CI/CD pipeline uses shallow clone for speed but build needs tag information
  • --no-tags flag used during clone
  • Build tool uses git describe which requires tag ancestry
  • Monorepo versioning depends on tag reachability

Step-by-Step Fix

  1. 1.Fetch tags after a shallow clone:
  2. 2.```bash
  3. 3.git clone --depth 1 https://github.com/org/repo.git
  4. 4.cd repo
  5. 5.git fetch --tags --force
  6. 6.git describe --tags
  7. 7.# Now works
  8. 8.`
  9. 9.Use sufficient depth to include the nearest tag:
  10. 10.```bash
  11. 11.# Clone with enough history to reach tags
  12. 12.git clone --depth 50 https://github.com/org/repo.git
  13. 13.`
  14. 14.For CI/CD pipelines, configure proper clone depth. In GitHub Actions:
  15. 15.```yaml
  16. 16.steps:
  17. 17.- uses: actions/checkout@v4
  18. 18.with:
  19. 19.fetch-depth: 0 # Full clone with all history and tags
  20. 20.`
  21. 21.Or if you need speed but also tags:
  22. 22.```yaml
  23. 23.steps:
  24. 24.- uses: actions/checkout@v4
  25. 25.with:
  26. 26.fetch-depth: 0
  27. 27.fetch-tags: true
  28. 28.`
  29. 29.For GitLab CI:
  30. 30.```yaml
  31. 31.variables:
  32. 32.GIT_STRATEGY: clone
  33. 33.GIT_DEPTH: 0
  34. 34.`
  35. 35.Unshallow an existing shallow clone:
  36. 36.```bash
  37. 37.git fetch --unshallow
  38. 38.git fetch --tags
  39. 39.`
  40. 40.This converts a shallow clone to a full clone with all history.

Prevention

  • Use fetch-depth: 0 (full clone) in CI/CD when version detection is needed
  • If using shallow clone for speed, always follow with git fetch --tags
  • Configure build tools to handle missing git metadata gracefully (fallback to environment variable)
  • Use GIT_DESCRIBE_TAG environment variable in CI/CD as an alternative to git describe
  • Document the minimum clone depth required for your build tools
  • Test your build with both shallow and full clones to detect dependencies on git history
  • Consider using a version file (VERSION or package.json) as the single source of truth
  • For npm packages, use npm version which updates package.json directly