Git
简体中文 ▾ Topics ▾ Latest version ▾ git-describe last updated in 2.44.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，而这个blob本身就描述了从HEAD反向修订中出现的第一个提交。

选项

<提交号>…​

要描述的类似于承诺的对象名称。 如果省略，则默认为HEAD。

--dirty[=<标记>]
--broken[=<标记>]

描述工作树的状态。 当工作树与HEAD匹配时，其输出与 "git describe HEAD "相同。 如果工作树有本地修改，"-dirty "会被附加到它上面。 如果一个仓库被破坏了，而Git不能确定是否有本地修改，Git会出错，除非给了`--broken'，它将附加后缀"-broken"。

--all

而不是只使用注释的标签，使用在`refs/`命名空间中发现的任何ref。 这个选项可以匹配任何已知的分支、远程跟踪分支或轻量级标签。

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

只考虑与给定的 glob(7) 模式匹配的标签，不包括 "refs/tags/" 前缀。如果和`--all`一起使用，它也会考虑匹配该模式的本地分支和远程跟踪引用，分别排除 "refs/heads/"和 "refs/remotes/"前缀；其他类型的引用永远不会被考虑。如果给出多次，将积累一个模式列表，匹配任何模式的标签都会被考虑。 使用`--no-match`来清除和重置模式列表。

--exclude <模式>

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

--always

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

--first-parent

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

实例

使用类似 git.git current tree 这样的工具，我得到的结果是：

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

也就是说，我的 "父 "分支的当前头部是基于v1.0.4的，但由于它在此基础上有一些提交，所以describe在最后添加了额外的提交数量（"14"）和提交本身的缩写对象名称（"2414721"）。

额外提交的次数是 "git log v1.0.4.parent" 显示的提交次数。 哈希后缀是"-g" + 父提交（即 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，那么回溯将只考虑每个提交的第一个父级。

如果在行走过程中发现了多个标签，那么将选择与输入的commit-ish相差最少的标签并输出。 这里，最小的提交差异被定义为 "git log tag…​input "所显示的提交数量将是最小的提交数量。

漏洞

树对象以及不指向提交的标签对象，不能被描述。 在描述 blob 时，指向 blob 的轻量级标签会被忽略，但尽管轻量级标签是有利的，blob 仍然被描述为 <提交号>:<路径>。

GIT

属于 git[1] 文档

scroll-to-top