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

名称

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

概要

gitrevisions

描述

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

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

指定修订版本

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

注意
 本文档显示了 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 期间，记录操作当前停止的提交，无论是由于冲突还是交互式 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 文件。 虽然 ref 名称编码未指定，但首选 UTF-8，因为某些输出处理可能会假定 UTF-8 中的 ref 名称。

@

*@* 单独是 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}*

您可以将 *@* 构造与空引用部分一起使用，以获取当前分支的 reflog 条目。 例如，如果您在分支 *blabla* 上，则 *@{1}* 与 *blabla@{1}* 含义相同。

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

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

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

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

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

后缀 *@{push}* 报告在检出 branchname 时（如果未指定分支名称，则为当前 HEAD）运行 git push 时“我们将推送到的”分支。 与 *@{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）作用于一组提交，而不仅仅是一个提交。

对于这些命令，使用上一节中描述的符号指定单个修订版本意味着从给定提交可reachable的提交集。

指定多个修订版本意味着从任何给定提交可访问的提交集。

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

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

提交排除

^<rev> (插入符号) 符号

要排除从提交可访问的提交，请使用前缀^符号。 例如^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分支fork以来我做了什么？” 类似地，..origin是HEAD..origin的简写形式，并询问“自从我从他们那里fork以来，origin做了什么？” 请注意，..表示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

属于 git[1] 套件的一部分

scroll-to-top