Git

gitrevisions 最后更新于 2.42.0

名称

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

概要

gitrevisions

描述

许多 Git 命令以修订版参数作为参数。根据命令的不同，它们表示一个特定的提交，或者对于遍历修订版图的命令（例如 git-log[1]），表示从该提交可达的所有提交。对于遍历修订版图的命令，还可以显式地指定一个修订版范围。

此外，一些 Git 命令（例如 git-show[1] 和 git-push[1]）还可以接受修订版参数，这些参数表示除提交以外的其他对象，例如 blob（“文件”）或树（“文件的目录”）。

指定修订版

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

注意	此文档显示了 git 所见的“原始”语法。shell 和其他 UI 可能需要额外的引号来保护特殊字符并避免单词分割。

<sha1>，例如 dae86e1950b1277e545cee180551750029cfe735，dae86e

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

<describeOutput>，例如 v1.7.4.2-679-g3bee7fb

git describe 的输出；即一个最近的标签，可选地后跟一个连字符和一个提交数量，后跟一个连字符、一个 g 和一个缩写后的对象名称。

<refname>，例如 master，heads/master，refs/heads/master

一个符号 ref 名称。例如，master 通常表示 refs/heads/master 引用的提交对象。如果你碰巧同时拥有 heads/master 和 tags/master，你可以明确地说 heads/master 来告诉 Git 你指的是哪个。如果存在歧义，则通过以下规则中的第一个匹配项消除 <refname> 的歧义

如果 $GIT_DIR/<refname> 存在，那就是你指的是什么（这通常只对 HEAD、FETCH_HEAD、ORIG_HEAD、MERGE_HEAD、REBASE_HEAD、REVERT_HEAD、CHERRY_PICK_HEAD、BISECT_HEAD 和 AUTO_MERGE 有用）；
否则，如果存在，则为 refs/<refname>；
否则，如果存在，则为 refs/tags/<refname>；
否则，如果存在，则为 refs/heads/<refname>；
否则，如果存在，则为 refs/remotes/<refname>；
否则，如果存在，则为 refs/remotes/<refname>/HEAD。

HEAD

命名你基于工作树中的更改的提交。

FETCH_HEAD

记录你使用上次 git fetch 调用从远程仓库获取的分支。

ORIG_HEAD

由以剧烈方式移动你的 HEAD 的命令（git am、git merge、git rebase、git reset）创建，用于记录它们操作之前 HEAD 的位置，以便你可以轻松地将分支的顶端更改回运行它们之前的状态。

MERGE_HEAD

记录你在运行 git merge 时合并到你的分支中的提交。

REBASE_HEAD

在变基过程中，记录当前停止操作的提交，无论是由于冲突还是交互式变基中的 edit 命令。

REVERT_HEAD

记录你在运行 git revert 时反转的提交。

CHERRY_PICK_HEAD

记录你在运行 git cherry-pick 时 cherry-pick 的提交。

BISECT_HEAD

记录你在运行 git bisect --no-checkout 时要测试的当前提交。

AUTO_MERGE

记录一个树对象，该对象对应于 ort 合并策略在合并操作导致冲突时写入工作树的状态。

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

@

单独的 @ 是 HEAD 的简写。

[<refname>]@{<date>}，例如 master@{yesterday}，HEAD@{5 minutes ago}

一个 ref 后跟后缀 @，后面是一个用花括号括起来的日期规范（例如 {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>）。请注意，这会查找你本地 ref 在给定时间的状态；例如，上周你的本地 master 分支中的内容。如果你想查看在特定时间内进行的提交，请参阅 --since 和 --until。

<refname>@{<n>}，例如 master@{1}

一个 ref 后跟后缀 @，后面是一个用花括号括起来的序数规范（例如 {1}、{15}），指定该 ref 的第 n 个先前值。例如，master@{1} 是 master 的直接先前值，而 master@{5} 是 master 的第 5 个先前值。此后缀只能紧跟在 ref 名称之后，并且该 ref 必须具有现有的日志（$GIT_DIR/logs/<refname>）。

@{<n>}，例如 @{1}

你可以使用带有空 ref 部分的 @ 结构来获取当前分支的 reflog 条目。例如，如果你位于分支 blabla 上，那么 @{1} 与 blabla@{1} 相同。

@{-<n>}，例如 @{-1}

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

[<branchname>]@{upstream}，例如 master@{upstream}，@{u}

一个分支 B 可以被设置为基于一个分支 X（使用 branch.<name>.merge 配置）在远程 R（使用 branch.<name>.remote 配置）上构建。B@{u} 指的是从远程 R 获取的分支 X 的远程跟踪分支，通常位于 refs/remotes/R/X。

[<branchname>]@{push}，例如 master@{push}，@{push}

后缀 @{push} 报告“我们将在其中推送的分支”，如果 branchname 被检出时运行 git push（或者如果未指定分支名称，则为当前 HEAD）。与 @{upstream} 相似，我们报告对应于该分支的远程跟踪分支。

以下是一个更清晰的示例

$ git config push.default current
$ git config remote.pushdefault myfork
$ git switch -c 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

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

当此后缀以大写字母拼写时，也是被接受的，无论大小写，意思都是一样的。

<rev>^[<n>]，例如：HEAD^, v1.5.1^0

修饰符 ^ 附加在修订参数之后，表示该提交对象的第一个父提交。^<n> 表示第 <n> 个父提交（即 <rev>^ 等同于 <rev>^1）。特殊情况，<rev>^0 表示提交本身，用于 <rev> 是指向提交对象的标签对象名称的时候。

<rev>~[<n>]，例如：HEAD~, master~3

修饰符 ~ 附加在修订参数之后，表示该提交对象的第一个父提交。修饰符 ~<n> 附加在修订参数之后，表示该提交对象的第 <n> 个祖先提交，只沿着第一个父提交进行回溯。例如，<rev>~3 等同于 <rev>^^^，也等同于 <rev>^1^1^1。有关此格式的用法示例，请参见下文。

<rev>^{<type>}，例如：v0.99.8^{commit}

修饰符 ^ 后面跟着一对花括号括起来的类型名称，表示递归地对 <rev> 所指的对象进行反向解析，直到找到一个类型为 <type> 的对象，或对象无法再反向解析（在这种情况下，会报错）。例如，如果 <rev> 是一个提交式，则 <rev>^{commit} 表示对应的提交对象。类似地，如果 <rev> 是一个树式，则 <rev>^{tree} 表示对应的树对象。<rev>^0 是 <rev>^{commit} 的简写形式。

<rev>^{object} 可以用来确保 <rev> 所指的对象存在，而不必要求 <rev> 是一个标签，也不必反向解析 <rev>；因为标签本身就是一个对象，所以即使要得到一个对象，也不需要反向解析一次。

<rev>^{tag} 可以用来确保 <rev> 标识的是一个存在的标签对象。

<rev>^{}，例如：v0.99.8^{}

修饰符 ^ 后面跟着一对空花括号，表示该对象可能是一个标签，并递归地反向解析该标签，直到找到一个非标签对象。

<rev>^{/<text>}，例如：HEAD^{/fix nasty bug}

修饰符 ^ 附加在修订参数之后，后面跟着一对花括号，其中包含以斜杠开头的文本，与下面 :/fix nasty bug 语法相同，只是它返回 ^ 之前的 <rev> 可达的最年轻的匹配提交。

:/<text>，例如：:/fix nasty bug

冒号后跟着斜杠，再跟着文本，表示一个提交，其提交信息匹配指定的正则表达式。此名称返回从任何引用（包括 HEAD）可达的最年轻的匹配提交。正则表达式可以匹配提交信息的任何部分。要匹配以字符串开头的信息，可以使用例如 :/^foo。特殊序列 :/! 预留用于修饰匹配的内容。:/!-foo 执行否定匹配，而 :/!!foo 匹配文字 ! 字符，后面跟着 foo。任何其他以 :/! 开头的序列目前都保留。根据给定的文本，shell 的词语拆分规则可能需要额外的引用。

<rev>:<path>，例如：HEAD:README，master:./README

修饰符 : 后面跟着路径，表示 : 之前部分所指的树式对象中，给定路径处的 blob 或树。以 ./ 或 ../ 开头的路径相对于当前工作目录。给定的路径将被转换为相对于工作树根目录的路径。这在从具有与工作树相同树结构的提交或树中访问 blob 或树时最有用。

:[<n>:]<path>，例如：: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
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 这样的历史遍历命令操作的是一组提交，而不仅仅是一个提交。

对于这些命令，使用上一节中描述的符号指定单个修订，表示从给定提交 可达 的提交集。

指定多个修订，表示从任何给定提交可达的提交集。

提交的可达集是指该提交本身及其祖先链中的提交。

有几种符号可以用来指定一组连接的提交（称为“修订范围”），如下所示。

提交排除

^<rev>（插入符号）符号: 要排除从提交可达的提交，使用前缀 ^ 符号。例如，^r1 r2 表示从 r2 可达的提交，但不包括从 r1 可达的提交（即 r1 及其祖先）。

点状范围符号

..（双点）范围符号: ^r1 r2 集合运算出现的频率很高，因此有简写形式。当你拥有两个提交 r1 和 r2（根据 SPECIFYING REVISIONS 中解释的语法命名）时，你可以要求从 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 分支分叉以来，我做了什么？”类似地，..origin 是 HEAD..origin 的简写形式，表示“自从我从他们那里分叉以来，origin 做了什么？”注意，.. 表示 HEAD..HEAD，这是一个空的范围，既可以从 HEAD 可达，也可以从 HEAD 不可达。

专门设计用来接收两个不同范围的命令（例如，"git range-diff R1 R2" 用于比较两个范围）是存在的，但它们是例外。除非另有说明，否则所有操作提交集的 "git" 命令都操作单个修订范围。换句话说，将两个“双点范围符号”并排写在一起，例如

$ git log A..B C..D

对于大多数命令来说，不代表指定两个修订范围。相反，它将命名一个单一的连接的提交集，即从 B 或 D 可达的提交，但不包括从 A 或 C 可达的提交。在像这样的线性历史中

---A---B---o---o---C---D

由于 A 和 B 可以从 C 可达，因此由这两个点状范围指定的修订范围是单个提交 D。

其他 <rev>^ 父提交简写符号

还有另外三种简写形式，特别适用于合并提交，用于命名由一个提交及其父提交组成的集合。

r1^@ 符号表示 r1 的所有父提交。

r1^! 符号包括提交 r1，但不包括其所有父提交。它本身表示单个提交 r1。

<rev>^-[<n>] 符号包括 <rev>，但不包括第 <n> 个父提交（即 <rev>^<n>..<rev> 的简写形式），如果省略 <n>，则 <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>^@，例如：HEAD^@: 修饰符 ^ 后面跟着一个 at 符号，与列出 <rev> 的所有父提交相同（表示包括从其父提交可达的任何内容，但不包括提交本身）。
<rev>^!，例如：HEAD^!: 修饰符 ^ 后面跟着一个感叹号，与给定提交 <rev> 及其所有父提交，并在其前面加上 ^ 来排除它们（及其祖先）相同。
<rev>^-<n>，例如：HEAD^-, HEAD^-2: 等效于<rev>^<n>..<rev>，如果没有给出<n>，则<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

另请参见

git-rev-parse[1]

是 git[1] 套件的一部分

设置和配置

获取和创建项目

基本快照

分支和合并

共享和更新项目

检查和比较

补丁

调试

邮件

外部系统

服务器管理

指南

管理

底层命令

名称

概要

描述