git describe 是什么
git describe 基于从当前提交可达的最近标签生成人类可读的版本描述，格式是「标签-提交数-g 短哈希」，例如 v1.8.0-12-gabc1234 表示从 v1.8.0 起又有 12 个提交，当前提交短哈希 abc1234。默认只认附注标签（annotated tag），轻量标签要加 --tags 才会被使用；无标签时可用 --always 回退成裸哈希，--dirty 会在有未提交改动时追加后缀。CI 里常用它生成构建版本号注入产物（二进制版本字符串、镜像 tag、监控标签），比手写版本号可靠，也能从线上版本快速定位代码位置。
基本信息
| 基本用法 | git describe --tags |
|---|---|
| 常用参数 | --always 无标签回退、--dirty 标记改动、--match 限定模式 |
| 输出解读 | v1.8.0-12-gabc1234 = 距 v1.8.0 有 12 个提交 |
| 标签类型 | 默认只认附注标签，轻量标签要 --tags |
| 构建注入 | 生成开发版本号替代手写 |
典型使用场景
- CI 构建号：每次构建生成唯一且可读的版本字符串。
- 发布包命名：包名带上版本与提交距离，追溯方便。
- 二进制版本：编译时注入版本字符串，--version 直接可见。
- 定位部署：线上上报的版本号直接对应代码位置。
- dirty 检测：构建混入未提交改动时发出警告。
- 关联审计：与镜像标签、监控面板版本字段对齐。
示例
示例
git describe --tags --match 'v*' --always
git describe --tags --dirty
# 构建脚本注入:
VERSION=$(git describe --tags --always --dirty)
go build -ldflags "-X main.version=$VERSION" ./cmd/app输出逐段读法
| 片段 | 含义 | 示例 |
|---|---|---|
| 起始标签 | 最近可达标签 | v1.8.0 |
| 中间数字 | 距标签的提交数 | 12 |
| g 加哈希 | 当前提交短哈希 | gabc1234 |
| dirty 后缀 | 有未提交改动 | -dirty |
浅克隆是最大坑：CI 默认浅克隆不含历史与标签，describe 会失准；设置 fetch-depth: 0 或显式拉取标签。
默认只认附注标签：项目习惯打轻量标签时，不加 --tags 会直接退化成哈希输出。
本地打的标签未推送同样不可见：记得把标签推到远端，CI 才能识别。
与语义化版本流程配合：发布在标签处定格完整版本，describe 负责提交级的开发版本字符串，两者分工明确。
提交数是「距最近标签」而非距上次发布：标签打得随意，数字就失去参考价值，先立标签纪律。