Git
简体中文 ▾ Topics ▾ Latest version ▾ git-describe last updated in 2.43.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反向修订中出现的第一个提交。

选项

<commit-ish>…​

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

--dirty[=<mark>]
--broken[=<mark>]

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

--all

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

--tags

而不是只使用注释过的标签，使用在`refs/tags`命名空间中发现的任何标签。 这个选项可以匹配轻量级（非注释的）标签。

--contains

与其寻找提交前的标签，不如寻找提交后的标签，从而包含该标签。 自动暗示—​标签。

--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`来清除和重置模式列表。

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

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

The number of additional commits is the number of commits which would be displayed by "git log v1.0.4..parent". The hash suffix is "-g" + an unambiguous abbreviation for the tip commit of parent (which was 2414721b194453f058079d897d13c4e377f92dc6). The length of the abbreviation scales as the repository grows, using the approximate number of objects in the repository and a bit of math around the birthday paradox, and defaults to a minimum of 7. The "g" prefix stands for "git" and is used to allow describing the version of a software depending on the SCM the software is managed with. This is useful in an environment where people may use different SCMs.

对一个标签名做 "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的情况下，该命令可以用来寻找最接近的没有任何后缀的tagname。

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

漏洞

Tree objects as well as tag objects not pointing at commits, cannot be described. When describing blobs, the lightweight tags pointing at blobs are ignored, but the blob is still described as <commit-ish>:<path> despite the lightweight tag being favorable.

GIT

属于 git[1] 文档

scroll-to-top