git describe

名称

git-describe - 描述一个使用它可以访问的最近标签的提交

概要

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

描述

该命令查找可从提交中访问的最新标记。如果标签指向提交，则只显示标签。否则，它会将标记名称与标记对象顶部的附加提交数量以及最近提交的缩写对象名称后缀相加。

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

选项

<commit-ish>…​

提交对象名称来描述。如果省略，则默认为 HEAD。

--dirty=<mark> --broken=<mark>

描述工作树的状态。当工作树与 HEAD 匹配时，输出与“git describe HEAD”相同。如果工作树具有本地修改，则将“-dirty”附加到其上。如果存储库已损坏， Git 无法确定是否存在本地修改，那么 Git 将会出错，除非给出了“--broken”，而是附加后缀“-broken”。

--all

不要只使用带注释的标签，而应使用refs/名称空间中的任何参考。该选项可以匹配任何已知的分支，远程追踪分支或轻量级标签。

--tags

不要只使用带注释的标签，而要使用refs/tags名称空间中的任何标签。该选项可以匹配一个轻量级（未注释）的标签。

--contains

不是找到提交之前的标签，而是找到提交之后的标签，因此包含它。自动地表明 - 标签。

--abbrev=<n>

使用默认的7位十六进制数字作为缩写对象名称，而不是使用<n>数字或根据需要的数字来组成一个唯一的对象名称。0 的<n>将抑制长格式，只显示最接近的标签。

--candidates=<n>

而不是只考虑最近的10个标签作为描述输入提交的候选者，而是考虑到候选者。将<n>增加到10以上会稍微长一些，但可能会产生更准确的结果。0的<n>将只会导致精确的匹配输出。

--exact-match

只输出完全匹配（一个标签直接引用提供的提交）。这是--candidates = 0的同义词。

--debug

精确地显示正在使用的搜索策略的信息以标准错误。标签名称仍将打印到标准输出。

--long

即使与标签匹配，始终输出长格式（标签，提交数量和缩写提交名称）。当您想要在“describe”输出中查看部分提交对象名称时，即使提交的问题恰好是标记的版本时，这也很有用。它不会仅仅发出标签名称，而是会描述这样的提交，如v1.2-0-gdeadbee（自从标签 v1.2指向 object deadbee 之后的第0次提交）。

--match <pattern>

只考虑与给定glob(7)模式匹配的标签，不包括“refs / tags /”前缀。这可以用来避免从存储库泄漏私有标签。如果给定多次，模式列表将被累积，并且将考虑匹配任何模式的标签。使用--no-match清除和复位的模式列表。

--exclude <pattern>

不要考虑与给定glob(7)模式匹配的标签，不包括“refs / tags /”前缀。这可以用来缩小标签空间并仅查找符合某些有意义标准的标签。如果给定多次，模式列表将被累积，并且匹配任何模式的标签将被排除。当与--match 结合使用时，当匹配至少一个匹配模式并且不匹配任何 - 排除模式时，将会考虑它。使用--no-exclude清除和复位的模式列表。

--always

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

--first-parent

在查看合并提交后，只跟踪第一个父提交。当您希望不匹配目标提交历史记录中合并的分支上的标签时，这非常有用。

示例

有了些像 git.git 流树之类的东西，我得到：

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

即我的“父”分支的当前头是基于v1.0.4，但由于它有几个提交，describe 已经增加了提交的次数（“14”）和提交的缩写对象名本身（“2414721”）最后。

额外提交的数量是“git log v1.0.4..parent”显示的提交数量。哈希后缀是“-g”+父代提示提交（这是2414721b194453f058079d897d13c4e377f92dc6）的7个字符的缩写。“g”前缀代表“git”，用于描述软件的版本，具体取决于管理软件的 SCM。这在人们可能使用不同 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

请注意，如果今天输入这些命令，那么获得的后缀可能比 Linus 在运行这些命令时看到的要长，因为您的 Git 存储库可能具有新的提交，其对象名称以975b开头，并且当时不存在，“ - g975b“后缀可能不足以消除这些提交的歧义。

搜索策略

对于每个提交的提交，git describe都将首先查找一个标签，该标签完全标记该提交。注释标签总是比轻量级标签更受欢迎，并且具有较新日期的标签始终优先于较早日期的标签。如果找到完全匹配，则会输出其名称并停止搜索。

如果没有找到完全匹配，git describe则会遍历提交历史记录以找到已标记的祖先提交。祖先的标签将与输入提交的 SHA-1的缩写一起输出。如果--first-parent被指定，则散步将只考虑每个提交的第一个父代。

如果在步行期间找到多个标签，那么将选择并输出具有与输入提交不同的最少提交的标签。这里最少的提交不同的定义为提交的数量git log tag..input将会是最小的提交数量。