gitrevisions

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

名称

gitrevisions - 为Git指定修订版和范围

概要

gitrevisions

描述

许多Git命令将修订参数作为参数。根据命令，它们表示特定的提交，或者对于遍历修订图的命令（例如 git-log [1] ），表示可以从该提交到达的所有提交。对于遍历修订图的命令，还可以明确指定一系列修订。

另外，一些Git命令（例如 git-show [1] 和 git-push [1] ）也可以采用表示除提交之外的其他对象的修订参数，例如： blob（“文件”）或树（“文件目录”）。

指定修订

修订参数< rev> 通常（但不一定）命名提交对象。它使用所谓的扩展SHA-1 语法。以下是拼写对象名称的各种方法。列表末尾附近列出的名称包含提交中包含的树和blob。

| 注意 | 本文档显示了git看到的“原始”语法。 shell和其他UI可能需要额外的引用来保护特殊字符并避免单词拆分。 |

  1.  <sha1>, e.g. dae86e1950b1277e545cee180551750029cfe735, dae86e

完整的SHA-1对象名称（40字节十六进制字符串），或存储库中唯一的前导子字符串。例如。如果存储库中没有其他对象以dae86e开头的对象，则dae86e1950b1277e545cee180551750029cfe735和dae86e都命名相同的提交对象。

  1.  <describeOutput>, e.g. v1.7.4.2-679-g3bee7fb

git describe的输出;即，最接近的标签，可选地后跟破折号和多次提交，然后是破折号， g 和缩写的对象名称。

  1.  <refname>, e.g. master, heads/master, refs/heads/master

一个象征性的引用名称。例如。 master 通常表示 refs / heads / master 引用的提交对象。如果您碰巧同时拥有磁头/主控和标签/主控，您可以明确地说磁头/主控告诉Git您的意思。当含糊不清时，< refname> 通过以下规则中的第一场比赛消除歧义：

  1. 如果 $ GIT_DIR /< refname> 存在，这就是你的意思（这通常只适用于HEAD，FETCH_HEAD，ORIG_HEAD，MERGE_HEAD和CHERRY_PICK_HEAD）;

  2. 否则， refs /< refname> 如果存在;

  3. 否则， refs / tags /< refname> 如果存在;

  4. 否则， refs / heads /< refname> 如果存在;

  5. 否则， refs / remotes /< refname> 如果存在;

  6. 否则， refs / remotes /< refname> / HEAD （如果存在）。

    HEAD命名您基于工作树中的更改的提交。 FETCH_HEAD记录您使用上次git fetch调用从远程存储库中获取的分支。 ORIG_HEAD是由以大刀阔斧的方式移动HEAD的命令创建的，用于在操作之前记录HEAD的位置，以便您可以轻松地将分支的尖端更改回运行它们之前的状态。 MERGE_HEAD在运行git merge时记录您要合并到分支中的提交。当您运行git cherry-pick时，CHERRY_PICK_HEAD会记录您正在挑选的提交。

    请注意，上述任何 refs / * 情况可能来自 $ GIT_DIR / refs 目录或来自 $ GIT_DIR / packed-refs 文件。虽然未指定引用名称编码，但首选UTF-8，因为某些输出处理可能会假定使用UTF-8中的引用名称。

  1.  @

单独 @ 是HEAD的捷径。

  1.  <refname>@{<date>}, e.g. master@{yesterday}, HEAD@{5 minutes ago}

引用后跟 @ 后缀为日期规格括号对（例如 {昨天} ， {1个月2周3天1小时1秒前} 或 {1979-02-26 18:30:00} ）指定先前时间点的ref值。此后缀只能在引用名称后立即使用，并且引用必须具有现有日志（ $ GIT_DIR / logs /< ref> ）。请注意，这会在给定时间查找本地 ref的状态;例如，上周本地主分支机构的内容。如果要查看在特定时间内提交的提交，请参阅--since和--until。

  1.  <refname>@{<n>}, e.g. master@{1}

后缀为 @ 的后缀为括号对中的序数规范（例如 {1} ， {15} ）指定第n个先验那个参考的价值。例如 master @ {1} 是 master 的前一个值，而 master @ {5} 是 master 的第5个先前值]。此后缀只能在引用名称后立即使用，并且引用必须具有现有日志（ $ GIT_DIR / logs /< refname> ）。

  1.  @{<n>}, e.g. @{1}

您可以使用带有空参考部分的 @ 构造来获取当前分支的reflog条目。例如，如果你在分支 blabla ，那么 @ {1} 意味着与 blabla @ {1} 相同。

  1.  @{-<n>}, e.g. @{-1}

构造 @ { - < n>} 表示在当前分支/提交之前检出的第n个分支/提交。

  1.  <branchname>@{upstream}, e.g. master@{upstream}, @{u}

后缀 @ {upstream} 到分支机构（简称< branchname> @ {u} ）指的是由branchname指定的分支设置为在其上构建的分支（配置为branch.&lt;name&gt;.remote和branch.&lt;name&gt;.merge）。缺少的branchname默认为当前的。当拼写为大写时，这些后缀也被接受，无论如何它们都意味着相同的东西。

  1.  <branchname>@{push}, e.g. master@{push}, @{push}

后缀 @ {push} 报告分支“我们将推送到哪里”如果branchname在branchname被检出时运行（或者当前HEAD如果没有指定分支机构）。由于我们的推送目的地位于远程存储库中，当然，我们报告与该分支对应的本地跟踪分支（即 refs / remotes / 中的内容）。

这是一个让它更清晰的例子：

  1. $ git config push.default current
  2. $ git config remote.pushdefault myfork
  3. $ git checkout -b mybranch origin/master
  5. $ git rev-parse --symbolic-full-name @{upstream}
  6. refs/remotes/origin/master
  8. $ git rev-parse --symbolic-full-name @{push}
  9. refs/remotes/myfork/mybranch

请注意，在我们设置三角形工作流程的示例中，我们从一个位置拉出并推送到另一个位置。在非三角形工作流程中， @ {push} 与 @ {upstream} 相同，并且不需要它。

拼写为大写时也接受此后缀，无论情况如何都是相同的。

  1.  <rev>^, e.g. HEAD^, v1.5.1^0

修订参数的后缀 ^ 表示该提交对象的第一个父级。 ^< n> 表示第n个亲本（即< rev> ^ 等同于< rev> ^ ）。作为特殊规则，< rev> ^ 0 表示提交本身并且在< rev>时使用。 是引用提交对象的标记对象的对象名称。

  1.  <rev>~<n>, e.g. master~3

后缀〜< n> 到版本参数意味着提交对象是指定提交对象的第n代祖先，仅跟随第一个父对象。即< rev>〜相当于< rev> ^^^ ，其相当于< rev> ^ 1 ^ 1 ^ 。请参阅下文，了解此表单的用法。

  1.  <rev>^{<type>}, e.g. v0.99.8^{commit}

后缀 ^ 后跟括号对中包含的对象类型名称意味着在< rev>处取消引用对象。 递归地直到< type>类型的对象为止。找到或者不再解除引用对象（在这种情况下，barf）。例如，如果< rev> 是commit-ish，< rev> ^ {commit} 描述了相应的提交对象。类似地，如果< rev> 是树，< rev> ^ {tree} 描述了相应的树对象。 < rev> ^ 0 是< rev> ^ {commit} 的简写。

rev ^ {object} 可以用来确保 rev 命名一个存在的对象，而不需要 rev 作为标签，并且不需要解除引用 rev ;因为标签已经是一个对象，所以即使一次到达一个对象也不需要解除引用。

rev ^ {tag} 可用于确保 rev 标识现有标记对象。

  1.  <rev>^{}, e.g. v0.99.8^{}

后缀 ^ 后跟空括号对意味着该对象可以是标记，并递归取消引用标记，直到找到非标记对象。

  1.  <rev>^{/<text>}, e.g. HEAD^{/fix nasty bug}

后缀 ^ 到一个修订参数，后跟一个括号对，其中包含一个由斜杠引导的文本，与下面的：/ fix讨厌错误语法相同，只是它返回可以从< rev>到达的最年轻的匹配提交 ^ 之前的。

  1.  :/<text>, e.g. :/fix nasty bug

冒号后跟一个斜杠，后跟一个文本，命名一个提交，其提交消息与指定的正则表达式匹配。此名称返回可从任何ref访问的最新匹配提交，包括HEAD。正则表达式可以匹配提交消息的任何部分。为了匹配以字符串开头的消息，可以使用例如：/ ^ foo 。特殊序列：/！ 保留用于匹配的修饰符。 ：/！ - foo 执行负匹配，而：/ !! foo 匹配文字！ 字符，然后是 foo 。以开头的任何其他序列：/！ 暂时保留。根据给定的文本，shell的单词拆分规则可能需要额外的引用。

  1.  <rev>:<path>, e.g. HEAD:README, :README, master:./README

后缀：后跟一个路径，命名由冒号前部分命名的树形对象中给定路径上的blob或树。 ：path （在冒号前面有空部分）是下面描述的语法的特例：在给定路径的索引中记录的内容。以 ./ 或 ../ 开头的路径是相对于当前工作目录的。给定路径将转换为相对于工作树的根目录。这对于从具有与工作树具有相同树结构的提交或树来解决blob或树最有用。

  1.  :<n>:<path>, e.g. :0:README, :README

冒号，可选地后跟一个阶段号（0到3）和一个冒号，后跟一个路径，在给定路径的索引中命名一个blob对象。缺少的阶段编号（以及其后面的冒号）命名阶段0条目。在合并期间，阶段1是共同的祖先，阶段2是目标分支的版本（通常是当前分支），阶段3是正在合并的分支的版本。

以下是Jon Loeliger的插图。提交节点B和C都是提交节点A的父节点。父提交从左到右排序。

  1. G   H   I   J
  2.  \ /     \ /
  3.   D   E   F
  4.    \  |  / \
  5.     \ | /   |
  6.      \|/    |
  7.       B     C
  8.        \   /
  9.         \ /
  10.          A
  1. A =      = A^0
  2. B = A^   = A^1     = A~1
  3. C = A^2  = A^2
  4. D = A^^  = A^1^1   = A~2
  5. E = B^2  = A^^2
  6. F = B^3  = A^^3
  7. G = A^^^ = A^1^1^1 = A~3
  8. H = D^2  = B^^2    = A^^^2  = A~2^2
  9. I = F^   = B^3^    = A^^3^
  10. J = F^2  = B^3^2   = A^^3^2

指定范围

遍历诸如git log之类的命令的历史操作在一组提交上，而不仅仅是单个提交。

对于这些命令，使用上一节中描述的表示法指定单个修订版意味着来自给定提交的提交reachable集。

提交的可达集是提交本身和其祖先链中的提交。

提交排除

  1.  ^<rev> (caret) Notation

要排除从提交可到达的提交，使用前缀 ^ 表示法。例如。 ^ r1 r2 表示从 r2 可到达的提交，但排除可从 r1 （即 r1 及其祖先）到达的提交。

虚线范围符号

  1.  The .. (two-dot) Range Notation

^ r1 r2 设置操作经常出现，因此有一个简写。如果你有两个提交 r1 和 r2 （根据上面的SPECIFYING REVISIONS中解释的语法命名），你可以要求从r2可以访问的提交，不包括那些可以从r1到达的提交 ^ r1 r2 可以写成 r1..r2 。

  1.  The …​ (three-dot) Symmetric Difference Notation

类似的符号 r1 … r2 称为 r1 和 r2 的对称差异，定义为 r1 r2 - not $（git merge） -base —all r1 r2）。它是可以从 r1 （左侧）或 r2 （右侧）中的任何一个到达的提交集，但不是两者都可以。

在这两个简写符号中，您可以省略一端并将其默认为HEAD。例如，原点.. 是 origin..HEAD 的简写并询问“自从我从原点分支分叉后我做了什么？”同样， .origin 是 HEAD..origin 的简写，并询问“自从我从它们分叉后，起源做了什么？”注意 .. 将意味着 HEAD..HEAD ，这是一个空的范围，既可以从HEAD到达又无法到达。

其他< rev> ^父简写符号

存在三个其他的缩写，对于合并提交特别有用，用于命名由提交及其父提交形成的集合。

r1 ^ @ 符号表示 r1 的所有亲本。

r1 ^！ 表示法包含commit r1 但不包括其所有父母。这个符号本身表示单个提交 r1 。

< rev> ^ - < n> 符号包括< rev> 但不包括第n个亲本（即< rev> ^< n> ..< rev> 的简写），< n>如果没有给出， = 1。这通常对于合并提交很有用，您可以通过< commit> ^ - 来获取合并提交中合并的分支中的所有提交< commit> （包括< commit> 本身）。

虽然< rev> ^< n> 是关于指定单个提交父级，这三个符号也考虑其父级。例如你可以说 HEAD ^ 2 ^ @ ，但你不能说 HEAD ^ @ ^ 2 。

修订范围摘要

  1.  <rev>

包括可从< rev>到达的提交（即< rev>及其祖先）。

  1.  ^<rev>

排除可从< rev>到达的提交（即< rev>及其祖先）。

  1.  <rev1>..<rev2>

包括可从< rev2>到达的提交但不包括那些可以从< rev1>到达的那些。何时< rev1>或者< rev2>省略，默认为HEAD。

  1.  <rev1>...<rev2>

包括可从< rev1>到达的提交或者< rev2>但排除那两个可以访问的。何时< rev1>或者< rev2>省略，默认为HEAD。

  1.  <rev>^@, e.g. HEAD^@

后缀为 ^ 后跟at符号与列出< rev>的所有父项相同。 （意思是，包括从其父母可以访问的任何内容，但不包括提交本身）。

  1.  <rev>^!, e.g. HEAD^!

后缀为 ^ 后跟感叹号与提交< rev>相同。 然后它的所有父母都以 ^ 为前缀来排除它们（以及它们的祖先）。

  1.  <rev>^-<n>, e.g. HEAD^-, HEAD^-2

等同于< rev> ^< n> ..< rev> ，< n>如果没有给出， = 1。

以下是使用上面的Loeliger插图的一些示例，其中注释的扩展和选择中的每个步骤都经过仔细说明：

  1.    Args   Expanded arguments    Selected commits
  2.    D                            G H D
  3.    D F                          G H I J D F
  4.    ^G D                         H D
  5.    ^D B                         E I J F B
  6.    ^D B C                       E I J F B C
  7.    C                            I J F C
  8.    B..C   = ^B C                C
  9.    B...C  = B ^F C              G H D E B C
  10.    B^-    = B^..B
  11.       = ^B^1 B              E I J F B
  12.    C^@    = C^1
  13.       = F                   I J F
  14.    B^@    = B^1 B^2 B^3
  15.       = D E F               D G H E F I J
  16.    C^!    = C ^C^@
  17.       = C ^C^1
  18.       = C ^F                C
  19.    B^!    = B ^B^@
  20.       = B ^B^1 ^B^2 ^B^3
  21.       = B ^D ^E ^F          B
  22.    F^! D  = F ^I ^J D           G H D F

也可以看看

git-rev-parse [1]

GIT

部分 git [1] 套件