生成可读版本号
用标签描述任意提交，输出「标签加距离加短哈希」的形式，并可用附加标记表示工作区有改动。它常用于把构建号写进产物，让每个版本都能精确追溯到某个提交。
基本信息
| 默认行为 | 基于可达的附注标签生成描述 |
|---|---|
| 接受轻量标签 | 附加参数后轻量标签也能被描述 |
| 兜底输出 | 没有可用标签时退化为短哈希 |
| 脏工作区标记 | 表示当前工作区相对该提交存在改动 |
| 范围限定 | 可用匹配参数指定标签模式 |
典型使用场景
- 把构建号写进产物，便于日后追溯
- 发布前确认当前提交距离最近标签有多远
- 没有标签时仍生成可读的标识
- 对比两个构建产物分别来自哪个提交
- 排查线上运行的是哪一个版本
常用示例
常用示例
git describe --tags # 接受轻量标签
git describe --tags --always --dirty # 无标签时退化为短哈希
git describe --long # 始终输出完整三段式描述
git describe --match 'v1.*' # 只匹配指定前缀的标签
git describe --tags $(git rev-parse HEAD) # 对指定提交生成描述输出逐段读法
| 片段 | 含义 |
|---|---|
| 标签名 | 距离该提交最近的标签 |
| 距离数字 | 自该标签以来的提交数量 |
| 短哈希 | 当前提交的缩写哈希 |
| 脏标记 | 工作区相对该提交存在未提交改动 |
流水线把描述结果写进构建产物的版本号，可以精确追溯到具体提交，排查线上问题时不用靠人回忆。
浅克隆历史不完整时可能找不到标签，先补齐历史或改用兜底输出，否则构建号会退化成短哈希。
默认只认附注标签，全用轻量标签的仓库需要显式加参数，否则拿不到标签信息。
距离数字很实用：它说明一个提交离开标签已经走了多远，可用来判断某个构建是否落后于发布点。