简体中文 ▾ 主题 ▾ 最新版本 ▾ 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> 找到，而 <commit-ish> 本身描述了该 blob 在从 HEAD 反向修订遍历中出现的第一个提交。

选项

<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（自标签 v1.2 以来指向对象 deadbee…​的第 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

即，我的“parent”分支的当前 HEAD 基于 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，该命令可以使用分支 HEAD 作为引用，因此输出也显示引用路径

[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 将显示的提交数量是可能最小的数量。

BUG

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

GIT

Git[1] 套件的一部分

scroll-to-top