git-describe

原文： https://git-scm.com/docs/git-describe

名称

git-describe - 根据可用的ref给对象一个人类可读的名称

概要

  1. git describe [--all] [--tags] [--contains] [--abbrev=<n>] [<commit-ish>…​]
  2. git describe [--all] [--tags] [--contains] [--abbrev=<n>] --dirty[=<mark>]
  3. git describe <blob>

描述

该命令查找可从提交访问的最新标记。如果标记指向提交，则仅显示标记。否则，它将标记名称后缀为标记对象顶部的附加提交数和最近提交的缩写对象名称。结果是一个“人类可读”的对象名称，它也可用于标识对其他git命令的提交。

默认情况下（不带—all或—tags）git describe仅显示带注释的标签。有关创建带注释标签的更多信息，请参阅 git-tag [1] 的-a和-s选项。

如果给定对象引用blob，则将其描述为&lt;commit-ish&gt;:&lt;path&gt;，以便可以在&lt;commit-ish&gt;中的&lt;path&gt;处找到blob，它本身描述了在反向修订中出现此blob的第一次提交从HEAD步行。

OPTIONS

  1.  <commit-ish>…​

要描述的Commit-ish对象名称。如果省略，则默认为HEAD。

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

描述工作树的状态。当工作树与HEAD匹配时，输出与“git describe HEAD”相同。如果工作树具有本地修改，则附加“-dirty”。如果存储库已损坏并且Git无法确定是否存在本地修改，则Git将出错，除非给出“—broken”，而后缀为“-broken”。

  1.  --all

不要只使用带注释的标签，而是使用refs/命名空间中的任何引用。此选项可以匹配任何已知分支，远程跟踪分支或轻量级标记。

  1.  --tags

不使用带注释的标签，而是使用refs/tags命名空间中的任何标签。此选项可以匹配轻量级（非注释）标记。

  1.  --contains

而不是找到提交之前的标记，找到提交后出现的标记，从而包含它。自动暗示—tags。

  1.  --abbrev=<n>

不使用默认的7个十六进制数字作为缩写对象名称，而是使用< n>数字，或形成唯一对象名称所需的数字。 < n> 0将禁止长格式，仅显示最接近的标记。

  1.  --candidates=<n>

而不是仅仅考虑10个最近的标签作为描述输入提交的候选者，而是考虑到< n>。候选人。增加< n>超过10将需要稍长但可能产生更准确的结果。 < n>为0将导致仅输出完全匹配。

  1.  --exact-match

仅输出完全匹配（标记直接引用提供的提交）。这是—candidates = 0的同义词。

  1.  --debug

详细显示有关用于标准错误的搜索策略的信息。标签名称仍将打印到标准输出。

  1.  --long

即使与标记匹配，也始终输出长格式（标记，提交数和缩写提交名称）。当您想要在“describe”输出中查看提交对象名称的某些部分时，这很有用，即使有问题的提交恰好是标记版本。它不会仅仅发出标记名称，而是将这样的提交描述为v1.2-0-gdeadbee（自标记v1.2以来第0次提交指向对象deadbee …）。

  1.  --match <pattern>

仅考虑与给定glob(7)模式匹配的标记，不包括“refs / tags /”前缀。如果与--all一起使用，它还会考虑与模式匹配的本地分支和远程跟踪引用，分别排除“refs / heads /”和“refs / remotes /”前缀;从不考虑其他类型的参考。如果多次给出，将累积模式列表，并且将考虑匹配任何模式的标签。使用--no-match清除和重置模式列表。

  1.  --exclude <pattern>

不要考虑与给定glob(7)模式匹配的标记，不包括“refs / tags /”前缀。如果与--all一起使用，它也不会考虑与模式匹配的本地分支和远程跟踪引用，分别排除“refs / heads /”和“refs / remotes /”前缀;从不考虑其他类型的参考。如果多次给出，则将累积模式列表，并且将排除匹配任何模式的标签。与—match结合使用时，如果标记与至少一个匹配模式匹配且与任何—exclude模式不匹配，则会考虑使用该标记。使用--no-exclude清除和重置模式列表。

  1.  --always

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

  1.  --first-parent

在看到合并提交时，仅遵循第一个父提交。当您希望不匹配目标提交历史记录中合并的分支上的标记时，这非常有用。

例子

有了类似git.git当前树的东西，我得到：

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

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

附加提交的数量是“git log v1.0.4..parent”显示的提交数。哈希后缀是父项提示提交的“-g”+ 7-char缩写（即2414721b194453f058079d897d13c4e377f92dc6）。 “g”前缀代表“git”，用于根据管理软件的SCM描述软件版本。这在人们可能使用不同SCM的环境中很有用。

在标签名称上执行 git describe 只会显示标签名称：

  1. [torvalds@g5 git]$ git describe v1.0.4
  2. v1.0.4

使用—all，该命令可以使用分支头作为引用，因此输出也显示引用路径：

  1. [torvalds@g5 git]$ git describe --all --abbrev=4 v1.0.5^2
  2. tags/v1.0.0-21-g975b
  1. [torvalds@g5 git]$ git describe --all --abbrev=4 HEAD^
  2. heads/lt/describe-7-g975b

将—abbrev设置为0，该命令可用于查找最接近的标记名，不带任何后缀：

  1. [torvalds@g5 git]$ git describe --abbrev=0 v1.0.5^2
  2. tags/v1.0.0

请注意，如果今天键入这些命令，您获得的后缀可能比Linus在运行这些命令时看到的更长，因为您的Git存储库可能有新的提交，其对象名称以975b开头，当时不存在，并且“ - g975b“单独的后缀可能不足以消除这些提交的歧义。

搜索策略

对于每个提交的提交， git describe 将首先查找标记该提交的标记。带注释的标签将始终优先于轻量级标签，具有较新日期的标签将始终优先于具有较旧日期的标签。如果找到完全匹配，将输出其名称并停止搜索。

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

如果在步行期间发现多个标签，则将选择并输出具有与输入commit-ish不同的最少提交的标签。这里提交的最小不同定义为git log tag..input显示的提交数量将是可能的最小提交数量。

BUGS

无法描述树对象以及不指向提交的标记对象。在描述blob时，忽略指向blob的轻量级标记，但blob仍被描述为< committ-ish>：< path>尽管轻量级标签是有利的。

GIT

部分 git [1] 套件