git describe未返回距离HEAD最近预期标签的问题排查

git describe默认匹配标签的逻辑和多数人直觉不符：它不会优先选择语义版本号更高、或到HEAD线性距离更近的标签，而是从HEAD出发做广度优先遍历所有可达提交，选遍历过程中累计步数最少的可达标签作为基准。
你的场景里v3.0.0虽然从HEAD出发走「HEAD→r3合并提交→r3分支头」的路径仅2步，但由于v3.0.0打在被合并的r3侧分支提交上，Git默认遍历逻辑下，遍历到v1.0.0、v2.0.0时累计步数为13，遍历到v3.0.0时累计步数为14，因此最终选择了步数更小的v2.0.0作为基准输出。
你手动统计的git log --oneline vX.X.X..HEAD | wc -l是两个提交之间的差集提交数，和git describe内部遍历用的累计步数计算逻辑完全不同，因此结果不匹配。

根据CI场景的使用需求，选以下任意一种方案即可：

• 调整打标位置：每次将功能分支合并到主干后，直接在主干的合并提交上打版本标签，不要把版本标签打在被合并的功能分支侧的提交上。这种方式下标签永远在主干的第一父提交链上，git describe会直接命中最新标签，不会出现匹配到旧标签的问题。
• 增加遍历限制参数：执行git describe --first-parent，让Git仅沿着每个提交的第一父链（即主干主提交链，不会深入遍历被合并侧分支的内部提交）查找标签，只要版本标签都打在主干提交上，该参数可以彻底避免侧分支旧标签的干扰。
• 自定义标签选择逻辑：如果标签必须打在功能分支提交上，可以先通过git tag --sort=-version:refname --merged HEAD | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+$' | head -n1筛选出已经合并到当前分支、版本号最高的标签，再基于该标签计算提交数、提交哈希，手动拼接成vX.X.X-x-gxxxxxxx格式的版本串，完全绕过默认算法的选择问题。

调整后执行对应命令，即可得到预期的v3.0.0-2-g9a45651格式输出。

内容的提问来源于stack exchange，提问作者circus