git-describe

基于可用引用为对象提供人类可读的名称

概要

git describe [--all] [--tags] [--contains] [--abbrev=<n>] [<commit-ish>...]
git describe [--all] [--tags] [--contains] [--abbrev=<n>] --dirty[=<mark>]
git describe <blob>

描述

该命令查找可从提交访问的最近标签。如果标签指向提交，则仅显示标签。否则，它在标签名称后附加标记对象之上的额外提交数量和最近提交的缩写对象名称。结果是"人类可读"的对象名称，也可用于向其他 git 命令标识提交。

默认情况下（没有 --all 或 --tags）git describe 仅显示注释标签。有关创建注释标签的更多信息，请参阅 git-tag(1) 的 -a 和 -s 选项。

如果给定的对象引用 blob，它将被描述为 <commit-ish>:<path>，使得可以在 <commit-ish> 中的 <path> 处找到 blob，<commit-ish> 本身描述从 HEAD 开始的反向修订遍历中此 blob 出现的第一个提交。

选项

<commit-ish>...

要描述的类提交对象名称。如果省略则默认为 HEAD。

--dirty[=<mark>], --broken[=<mark>]

描述工作树的状态。当工作树与 HEAD 匹配时，输出与 git describe HEAD 相同。如果工作树有本地修改，则附加 -dirty。如果存储库损坏且 Git 无法确定是否有本地修改，Git 将报错退出，除非给出 --broken，则改为附加后缀 -broken。

--all

不仅使用注释标签，还使用在 refs/ 命名空间中找到的任何引用。此选项启用匹配任何已知分支、远程跟踪分支或轻量标签。

--tags

不仅使用注释标签，还使用在 refs/tags 命名空间中找到的任何标签。此选项启用匹配轻量（非注释）标签。

--contains

不是查找早于提交的标签，而是查找提交之后的标签，从而包含它。自动隐含 --tags。

--abbrev=<n>

不使用默认的十六进制数字数（将根据存储库中的对象数量变化，默认为 7），而是使用 <n> 位数字，或足以形成唯一对象名称的数字数。<n> 为 0 将抑制长格式，仅显示最近的标签。

--candidates=<n>

不仅考虑最近的 10 个标签作为描述输入提交的候选项，而是考虑最多 <n> 个候选项。将 <n> 增加到 10 以上将花费稍长时间但可能产生更准确的结果。<n> 为 0 将仅输出精确匹配。

--exact-match

仅输出精确匹配（标签直接引用提供的提交）。这是 --candidates=0 的同义词。

--debug

详细显示有关正在使用的搜索策略的信息到标准错误。标签名称仍将打印到标准输出。

--long

始终输出长格式（标签、提交数和缩写提交名），即使它匹配标签。当你想在 "describe" 输出中看到提交对象名称的部分时，即使相关碰巧是标记版本，这很有用。

--match <pattern>

仅考虑与给定 glob(7) 模式匹配的标签（不包括 "refs/tags/" 前缀）。如果与 --all 一起使用，它还考虑匹配模式的本地分支和远程跟踪引用。如果多次给出，将累积模式列表，匹配任何模式的标签将被考虑。使用 --no-match 清除和重置模式列表。

--exclude <pattern>

不考虑与给定 glob(7) 模式匹配的标签。与 --match 结合使用时，标签在匹配至少一个 --match 模式且不匹配任何 --exclude 模式时被考虑。使用 --no-exclude 清除和重置模式列表。

--always

显示唯一缩写的提交对象作为后备。

--first-parent

在看到合并提交时仅跟随第一个父提交。当你希望不匹配在目标提交历史中合并的分支上的标签时，这很有用。

示例

使用 git.git 当前树，我得到：

[torvalds@g5 git]$ git describe parent
v1.0.4-14-g2414721

即我的 "parent" 分支的当前头部基于 v1.0.4，但由于它上面有几个提交，describe 在末尾添加了额外提交数 ("14") 和提交本身的缩写对象名称 ("2414721")。

额外提交数是 git log v1.0.4..parent 将显示的提交数。哈希后缀是 "-g" 加上 parent 顶端提交的明确缩写（即 2414721b194453f058079d897d13c4e377f92dc6）。缩写的长度随存储库增长而扩展，使用存储库中对象的大致数量和围绕生日悖论的一些数学运算，默认最小为 7。"g" 前缀代表 "git"，用于允许描述使用 SCM 管理的软件的版本。

对标签名执行 git describe 将只显示标签名：

[torvalds@g5 git]$ git describe v1.0.4
v1.0.4

使用 --all，命令可以使用分支头作为引用，因此输出还显示引用路径：

[torvalds@g5 git]$ git describe --all --abbrev=4 v1.0.5^2
tags/v1.0.0-21-g975b

[torvalds@g5 git]$ git describe --all --abbrev=4 HEAD^
heads/lt/describe-7-g975b

将 --abbrev 设置为 0 时，命令可用于查找不带任何后缀的最近标签名：

[torvalds@g5 git]$ git describe --abbrev=0 v1.0.5^2
tags/v1.0.0

搜索策略

对于提供的每个类提交对象，git describe 将首先查找标记该提交的标签。注释标签始终优先于轻量标签，较新的标签始终优先于较旧的标签。如果找到精确匹配，将输出其名称并停止搜索。

如果未找到精确匹配，git describe 将向后遍历提交历史以定位已被标记的祖先提交。祖先的标签将与输入类提交的 SHA-1 缩写一起输出。如果指定了 --first-parent，则遍历将仅考虑每个提交的第一个父提交。

如果在遍历期间找到多个标签，则选择与输入类提交差异最少的标签并输出。

Bug

树对象以及不指向提交的标签对象无法被描述。描述 blob 时，指向 blob 的轻量标签被忽略，但 blob 仍被描述为 <commit-ish>:<path>，尽管轻量标签更可取。

Git

git(1) 套件的一部分