简体中文 ▾ 主题 ▾ 最新版本 ▾ 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 仅显示附注标签（annotated tags）。有关创建附注标签的更多信息，请参阅 git-tag[1] 的 -a 和 -s 选项。

如果给定的对象引用的是一个 blob（数据对象），它将被描述为 <commit-ish>:<path>，这样就可以在 <commit-ish> 的 <path> 路径下找到该 blob，而这个 commit-ish 本身描述了从 HEAD 开始反向遍历时该 blob 首次出现的第一个提交。

选项

<commit-ish>…​

要描述的 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 个标签作为描述输入 commit-ish 的候选，而是考虑最多 <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

即我“parent”分支的当前头部基于 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" 后缀可能不足以消除这些提交的歧义。

搜索策略

对于提供的每个 commit-ish，git describe 首先会寻找一个精确标记该提交的标签。附注标签总是优于轻量标签，日期较新的标签总是优于日期较旧的标签。如果找到精确匹配，将输出其名称并停止搜索。

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

如果在回溯过程中发现了多个标签，则将选择并输出与输入 commit-ish 差异提交数最少的标签。这里差异提交数最少被定义为：git log tag..input 显示的提交数量将是可能的最小数字。

BUG

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

GIT

Git[1] 套件的一部分