## 名称

gitrevisions - 指定 Git 的修订和范围

## 概要

gitrevisions

## 描述

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

另外，一些 Git 命令（例如 git-show [1]）也会使用修改参数来表示其他对象而不是提交，例如 blob （“文件”）或树（“文件目录”）。

## 指定修订

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

<sha1>, e.g. dae86e1950b1277e545cee180551750029cfe735, dae86e

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

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

输出来自`git describe`; 即最接近的标记，可选地后跟破折号和多个提交，后跟短划线， `g`和缩写对象名称。

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

符号参考名称。例如，`master`通常意味着由引用的提交对象`refs/heads/master`。如果你碰巧有两个`heads/master`和`tags/master`，你可以明确地说`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`。`CHERRY_PICK_HEAD`记录您在运行时正在挑选的提交`git cherry-pick`。

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

@

单独`@`是一个`HEAD`的捷径。

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

后面跟着`@`带括号中的后缀（例如`{yesterday}`，`{1 month 2 weeks 3 days 1 hour 1 second ago}`或`{1979-02-26 18:30:00}`）的后缀指定前一个时间点的 ref 的值。后缀只能在 ref 名称后面使用，并且 ref 必须具有现有的日志（`$GIT_DIR/logs/<ref>`）。请注意，这会在给定的时间查看当地裁判的状态; 例如`master`上周您当地的分支机构。如果您想查看某些时间内提交的内容，请参阅`--since`和`--until`。

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

后缀为`@`带括号的后缀（例如`{1}`，`{15}`）指定了 ref 的第n个前置值。例如`master@{1}`，`master`while `master@{5}`是第5个先前值的即时先验值`master`。该后缀只能在 ref 名称后面使用，并且 ref 必须具有现有的日志（`$GIT_DIR/logs/<refname>`）。

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

您可以使用带有`@`空引用部分的构造来获取当前分支的 reflog 条目。例如，如果您在分支上，`blabla`则`@{1}`意味着与之相同`blabla@{1}`。

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

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

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

`@{upstream}` branchname （简称`<branchname>@{u}`）的后缀是指由 branchname 指定的分支设置为在（使用`branch.<name>.remote`和`branch.<name>.merge`）配置的基础上构建的分支。缺少的 branchname 默认为当前的。当用大写拼写时，这些后缀也是可接受的，无论大小写是什么，它们都表示相同的事物。

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

如果在检出`@{push}`时`git push`运行`branchname`（或当前`HEAD`没有指定branchname），后缀将报告分支 “where we would push to” 。由于我们的推送目标位于远程存储库中，当然，我们会报告与该分支对应的本地跟踪分支（即，某处`refs/remotes/`）。

这里有一个例子可以使它更加清晰：

    $ git config push.default current

    $ git config remote.pushdefault myfork

    $ git checkout -b mybranch origin/master

    $ git rev-parse --symbolic-full-name @{upstream}refs/remotes/origin/master

    $ git rev-parse --symbolic-full-name @{push}refs/remotes/myfork/mybranch

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

当拼写成大写字母时，这个后缀也是可以接受的，无论大小写意思都是相同的。

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

修订参数的后缀`^`表示提交对象的第一个父代。`^<n>`意味着第n个父母（即`<rev>^`相当于`<rev>^1`）。作为一个特殊规则，`<rev>^0`意味着提交本身，并在`<rev>`引用提交对象的标记对象的对象名称时使用。

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

修订参数的后缀`~<n>`表示作为指定提交对象的第n代父类的提交对象，仅在第一个父代之后。即`<rev>~3`相当于`<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`识别现有的标签对象。

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

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

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

后缀`^`的修正参数，其次，它包含用斜线为首的文本的一对括号，是一样的`:/fix nasty bug`下面的语法不同之处在于它返回最年轻的匹配提交其是从`^`可到达`<rev>`之前。

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

一个冒号，跟一个斜线，后跟一个文本，命名提交消息与指定正则表达式匹配的提交。名称返回可从任何ref访问的最新匹配提交。正则表达式可以匹配提交消息的任何部分。要匹配以字符串开头的消息，可以使用例如`:/^foo`。特殊序列`:/!`保留给修饰符以匹配内容。`:/!-foo`执行否定匹配，同时`:/!!foo`匹配文字`!`字符，然后匹配`foo`。任何以其他序列开始的序列`:/!`现在都被保留。

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

后缀`:`后面跟着一个路径的名称是由冒号前部分命名的 tree-ish 对象中给定路径上的 blob 树。`:path`（在冒号前有一个空白部分）是下面描述的语法的特例：记录在给定路径索引处的内容。以当前工作目录开始`./`或`../`相对于当前工作目录的路径。给定的路径将被转换为相对于工作树的根目录。这对于从具有与工作树相同树结构的提交或树来处理 blob 树是非常有用的。

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

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

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

    G   H   I   J

     \ /    \ /

      D   E   F

       \  |  / \

        \ | /   |

         \|/    |

          B     C

           \   /

            \ /

             A

    A =      = A^0

    B = A^   = A^1     = A~1

    C = A^2  = A^2

    D = A^^  = A^1^1   = A~2

    E = B^2  = A^^2

    F = B^3  = A^^3

    G = A^^^ = A^1^1^1 = A~3

    H = D^2  = B^^2    = A^^^2  = A~2^2

    I = F^   = B^3^    = A^^3^

    J = F^2  = B^3^2   = A^^3^2

## 指定范围

历史遍历命令，例如`git log`对一组提交进行操作，而不仅仅是一次提交。

对于这些命令，使用上一节中描述的符号来指定单个修订，意味着`reachable`来自给定提交的一组提交。

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

### 提交排除项

^<rev> (caret) Notation

要排除提交可达的提交，使用前缀`^`符号。例如，`^r1 r2`意味着提交可达，`r2`但不包括从`r1`（即`r1`其祖先）可达的。

### 虚线表示法

（双点）范围标识

`^r1 r2`组操作似乎经常有它的简写。当你有两个提交`r1`并且`r2`（根据上面指定版本中所述的语法命名）时，你可以要求提交从r2到达的提交，但不包括那些从r1可到达的提交，`^r1 r2`它可以写为`r1..r2`。

（三点）对称差符号

类似的符号`r1...r2`被称为和的对称差，`r1`被`r2`定义为`r1 r2 --not $(git merge-base --all r1 r2)`。它是从`r1`（左侧）或`r2`（右侧）中的任一个可达的提交集合，但不是来自两者。

在这两个简写符号中，可以省略一端，并将其默认为 HEAD 。例如，`origin..`是一个简写，`origin..HEAD`并问“自从我从原始分支分出后，我做了什么？” 同样，它`..origin`也是一种速记，`HEAD..origin`并问道：“我从他们身上分离出来后，起源究竟发生了什么？” 请注意，`..`这意味着`HEAD..HEAD`空白区域可以从 HEAD 到达和无法到达。

### Other <rev>^ Parent Shorthand Notations

还有三个其他的shorthands，对于合并提交，对于由提交和它的父代提交形成的集合进行命名特别有用。

`r1^@`符号表示的所有父代`r1`。

`r1^!`表示包括提交`r1`但排除其所有父代。这个符号本身表示单个提交`r1`。

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

虽然`<rev>^<n>`是关于指定一个单一的承诺父母，这三种表示法也考虑其父母。例如，你可以说`HEAD^2^@`，但是你不能说`HEAD^@^2`。

## 修订范围摘要

<rev>

包含从<rev>（即<rev>及其祖先）访问的提交。

^<rev>

排除从<rev>（即<rev>及其祖先）访问的提交。

<rev1>..<rev2>

包含从<rev2>访问的提交，但不包括从<rev1>访问的提交。当<rev1>或<rev2>被省略时，它默认为`HEAD`。

<rev1>...<rev2>

包含从<rev1>或<rev2>访问的提交，但排除可从两者访问的提交。当<rev1>或<rev2>被省略时，它默认为`HEAD`。

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

后缀`^`后跟一个符号与列出所有父母的`<rev>`意思相同（意思是，包括任何可从其父母获得的东西，但不包括承诺本身）。

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

后缀`^`后跟一个感叹号的方式与提交相同`<rev>`，然后它的所有父母前缀`^`以排除它们（和它们的祖先）。

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

相当于`<rev>^<n>..<rev>`，`<n>`如果没有给出，则= 1。

这里有一些使用上面的 Loeliger 插图的例子，仔细地说明了符号的扩展和选择中的每一步：

    Args   Expanded arguments    Selected commits

    D                            G H D

    D F                          G H I J D F^G D                         H D^D B                         E I J F B^D B C                       E I J F B C

    C                            I J F C

    B..C   = ^B C                C

    B...C  = B ^F C              G H D E B C

    B^-    = B^..B= ^B^1 B              E I J F B

    C^@    = C^1= F                   I J F

    B^@    = B^1 B^2 B^3= D E F               D G H E F I J

    C^!    = C ^C^@= C ^C^1= C ^F                C

    B^!    = B ^B^@= B ^B^1 ^B^2 ^B^3= B ^D ^E ^F          B

    F^! D  = F ^I ^J D           G H D F