gitrevisions

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

    概要

    gitrevisions

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

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

    指定修订

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

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

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

    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.  @{<n>}, e.g. @{1}

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

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

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

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

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

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

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

      请注意，在我们设置三角形工作流程的示例中，我们从一个位置拉出并推送到另一个位置。在非三角形工作流程中， @ {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

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

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

      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到达又无法到达。

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

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

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

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

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

      修订范围摘要

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

      1.  ^<rev>

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

        包括可从< 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>相同。 然后它的所有父母都以 ^ 为前缀来排除它们（以及它们的祖先）。

        等同于< 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

        git-rev-parse [1]

        GIT