简体中文 ▾ 主题 ▾ 最新版本 ▾ 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>，以便在 <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”输出中看到提交对象名称的某些部分，即使该提交恰好是已标记版本时，此选项很有用。它不会只输出标签名，而是将这样的提交描述为 v1.2-0-gdeadbee（自标签 v1.2 以来的第 0 个提交，指向对象 deadbee...）。

--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

即我的“父”分支的当前 HEAD 基于 v1.0.4，但由于它在该版本之上还有一些提交，describe 添加了额外提交的数量（“14”）和提交本身的缩写对象名称（“2414721”）在末尾。

额外提交的数量是“git log v1.0.4..parent”将显示的提交数量。哈希后缀是“-g”加上 parent 的 tip 提交（它是 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 将显示的提交数量是可能的最小数量。

BUG

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

GIT

Git[1] 套件的一部分