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>，这样可以在 <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（自指向对象 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

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

额外的提交数是 “git log v1.0.4..parent” 将显示的提交数。 哈希后缀是 “-g” + parent 的 tip 提交的明确缩写（即 2414721b194453f058079d897d13c4e377f92dc6）。 缩写的长度随着存储库的增长而缩放，使用存储库中对象的近似数量和围绕生日悖论的一些数学运算，默认最小值为 7。 “g” 前缀代表 “git”，用于允许描述依赖于软件管理的 SCM 的软件的版本。 这在人们可能使用不同 SCM 的环境中很有用。

对 tag-name 执行 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 显示的提交数量最小。

缺陷

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

GIT

属于 git[1] 套件的一部分

scroll-to-top