简体中文 ▾ 主题 ▾ 最新版本 ▾ gitrevisions 最后更新于 2.42.0

名称

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

概要

gitrevisions

描述

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

此外，某些 Git 命令（如 git-show[1] 和 git-push[1]）也可以接受指代除提交以外对象的修订版本参数，例如数据块（“文件”）或树（“文件目录”）。

指定修订版本

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

注意
 本文档显示了 git 所看到的“原始”语法。shell 和其他 UI 可能需要额外的引号来转义特殊字符并避免分词。
<sha1>，例如 dae86e1950b1277e545cee180551750029cfe735，dae86e

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

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

git describe 的输出；即最近的标签，后跟可选的连字符和提交数量，再后跟连字符、“g”以及缩写的对象名。

<refname>，例如 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, REBASE_HEAD, REVERT_HEAD, CHERRY_PICK_HEAD, BISECT_HEAD 和 AUTO_MERGE 有用）；

  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 的命令（git am, git merge, git rebase, git reset）创建，用于记录操作前的 HEAD 位置，以便你能轻松将分支顶端切回操作前的状态。

    MERGE_HEAD

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

    REBASE_HEAD

    在变基（rebase）期间，记录当前操作停止的提交（因为冲突或交互式变基中的 edit 命令）。

    REVERT_HEAD

    记录当你运行 git revert 时正在撤销的提交。

    CHERRY_PICK_HEAD

    记录当你运行 git cherry-pick 时正在拣选的提交。

    BISECT_HEAD

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

    AUTO_MERGE

    记录一个树对象，对应于当合并操作产生冲突时 ort 合并策略写入工作树的状态。

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

@

仅 @ 是 HEAD 的快捷方式。

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

引用后跟 @ 后缀及括号内的日期说明（例如 {yesterday}，{1 month 2 weeks 3 days 1 hour 1 second ago} 或 {1979-02-26 18:30:00}）指定了该引用在过去某个时间点的值。此后缀仅能紧跟引用名使用，且引用必须有现有的日志（$GIT_DIR/logs/<ref>）。注意，这是查找你在给定时间的本地引用状态；例如，你本地 master 分支上周的状态。如果你想查看在特定时间段内进行的提交，请参阅 --since 和 --until。

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

引用后跟 @ 后缀及括号内的序数说明（例如 {1}，{15}）指定了该引用的第 n 次先前值。例如 master@{1} 是 master 的紧邻先前值，而 master@{5} 是 master 的第 5 次先前值。此后缀仅能紧跟引用名使用，且引用必须有现有的日志（$GIT_DIR/logs/<refname>）。

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

可以使用带空引用部分的 @ 结构来访问当前分支的引用日志条目。例如，如果你在分支 blabla 上，则 @{1} 与 blabla@{1} 含义相同。

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

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

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

分支 B 可以设置为在远程 R（配置为 branch.<name>.remote）上的分支 X（配置为 branch.<name>.merge）之上构建。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> 是一个提交项（commit-ish），<rev>^{commit} 描述相应的提交对象。类似地，如果 <rev> 是一个树项（tree-ish），<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

: 后缀后跟路径，命名冒号前部分所指代树项对象中给定路径下的数据块或树。以 ./ 或 ../ 开头的路径是相对于当前工作目录的。给定路径将被转换为相对于工作树的根目录。这在从具有与工作树相同树结构的提交或树中寻址数据块或树时最有用。

:[<n>:]<path>，例如 :0:README，:README

冒号后可选跟暂存阶段编号（0 到 3）和冒号，再后跟路径，命名索引中给定路径下的数据块对象。缺少暂存阶段编号（及其后的冒号）则命名阶段 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（按照“指定修订版本”中解释的语法命名）时，可以通过 ^r1 r2 请求从 r2 可到达但从 r1 不可到达的提交，这可以写作 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> = 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^@

^ 后缀后跟 @ 符号与列出 <rev> 的所有父提交相同（即包括从其父提交可到达的任何内容，但不包括提交本身）。

<rev>^!，例如 HEAD^!

^ 后缀后跟惊叹号与提供提交 <rev> 及其所有以 ^ 为前缀的父提交以排除它们（及其祖先）相同。

<rev>^-<n>，例如 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

另请参阅

git-rev-parse[1]

GIT

Git[1] 套件的一部分