git-describe

根据最近的标签描述当前提交

补充说明

git describe 从最近的 tag 推导版本字符串，常用于构建版本号、制品命名和发布脚本。它依赖标签历史，浅克隆或没有 tag 时会退化。

常用示例

git describe --tags
git describe --tags --always
git describe --tags --dirty
git describe --tags --long
git describe --tags --match 'v*'
git describe --tags --exact-match
git describe --tags --abbrev=12 HEAD
git describe --tags --first-parent

易错点与排错

• 默认只使用 annotated tag；轻量 tag 需要加 --tags。
• 没有可用 tag 时会失败；脚本里加 --always 退回短哈希。
• 工作区有未提交改动时加 --dirty 才会显示后缀，否则版本看起来是干净的。
• 浅克隆可能缺少 tag 和中间历史；CI 要 fetch tags 或加深克隆。
• --long 强制输出 tag-距离-g哈希，适合需要精确提交的制品。
• --match 能过滤 tag 前缀，避免被无关标签干扰。
• describe 结果不是语义化版本；发布脚本仍要校验格式。

相关命令

• git — 版本控制
• git-archive — 导出源码
• goreleaser — 基于 tag 发布