Git
English ▾ 主题 ▾ 最新版本 ▾ git-describe 最后更新于 2.42.0

名称

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>，这样 blob 可以在 <commit-ish> 中的 <path> 处找到，它本身描述了从 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”输出中看到提交对象名称的部分内容时，这很有用，即使有问题的提交碰巧是标记版本。它不会只发出标签名称，而是会将这样的提交描述为 v1.2-0-gdeadbee（自指向对象 deadbee…​ 的标签 v1.2 之后的第 0 个提交）。

--match <pattern>

仅考虑与给定 glob(7) 模式匹配的标签，排除“refs/tags/”前缀。如果与 --all 一起使用，它还考虑与模式匹配的本地分支和远程跟踪引用，分别排除“refs/heads/”和“refs/remotes/”前缀；从不考虑其他类型的引用。如果多次给出，则将累积模式列表，并且将考虑与任何模式匹配的标签。使用 --no-match 清除并重置模式列表。

--exclude <pattern>

不考虑与给定 glob(7) 模式匹配的标签，排除“refs/tags/”前缀。如果与 --all 一起使用，它也不会考虑与模式匹配的本地分支和远程跟踪引用，分别排除“refs/heads/”和“refs/remotes/”前缀；从不考虑其他类型的引用。如果多次给出，则将累积模式列表，并且将排除与任何模式匹配的标签。当与 --match 结合使用时，当标签至少与一个 --match 模式匹配并且不与任何 --exclude 模式匹配时，将考虑该标签。使用 --no-exclude 清除并重置模式列表。

--always

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

--first-parent

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

示例

使用类似于 git.git 的当前树，我得到

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

即，我的“父”分支的当前头部基于 v1.0.4，但由于它在 v1.0.4 之上有一些提交，因此 describe 在末尾添加了其他提交数 (“14”) 和提交本身的缩写对象名称 (“2414721”) 。

其他提交数是指“git log v1.0.4..parent”将显示的提交数。哈希后缀是“-g”加上 parent 的顶端提交的唯一缩写（它是 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 将显示的提交数将是最少的提交数。

错误

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

GIT

git[1] 套件的一部分

scroll-to-top