简体中文 ▾ 主题 ▾ 最新版本 ▾ git-range-diff 最后更新于 2.52.0

名称

git-range-diff - 比较两个提交范围（例如分支的两个版本）

概要

git range-diff [--color=[<when>]] [--no-color] [<diff-options>]
	[--no-dual-color] [--creation-factor=<factor>]
	[--left-only | --right-only] [--diff-merges=<format>]
	[--remerge-diff]
	( <range1> <range2> | <rev1>…​<rev2> | <base> <rev1> <rev2> )
	[[--] <path>…​]

描述

此命令显示补丁系列的两个版本，或更一般地，两个提交范围（忽略合并提交）之间的差异。

如果存在 <path> 参数，这些提交范围将相应地受到限制。

为此，它首先从两个提交范围中找到相互对应的提交对。当两个补丁之间的差异（即作者信息、提交消息和提交差异）相对于补丁大小时足够小时，这两个提交就被认为是对应的。详情请参阅下方的“算法”部分。

最后，匹配的提交列表将按第二个提交范围的顺序显示，未匹配的提交将插入在它们的所有祖先节点显示之后。

指定提交范围有三种方式：

  • <range1> <range2>：任何一个提交范围都可以采用 <base>..<rev>、<rev>^! 或 <rev>^-<n> 的形式。更多详细信息，请参阅 gitrevisions[7] 中的 SPECIFYING RANGES。

  • <rev1>...<rev2>。这等同于 <rev2>..<rev1> <rev1>..<rev2>。

  • <base> <rev1> <rev2>：这等同于 <base>..<rev1> <base>..<rev2>。

选项

--no-dual-color

当提交差异不同时，git range-diff 会重新创建原始差异的着色，并添加外部 -/+ 差异标记，其背景为红色/绿色，以便更轻松地查看例如确切添加了哪些行的变更。

此外，仅存在于第一个提交范围中的提交差异行显示为“调暗”（可以使用 color.diff.<slot> 配置设置进行覆盖，其中 <slot> 是 contextDimmed、oldDimmed 或 newDimmed 之一），而仅存在于第二个提交范围中的提交差异行以粗体显示（可以使用 color.diff.<slot> 配置设置进行覆盖，其中 <slot> 是 contextBold、oldBold 或 newBold 之一）。

range-diff 将此称为“双重着色”。使用 --no-dual-color 可恢复为根据外部差异标记为所有行着色（在着色时完全忽略内部差异）。

--creation-factor=<percent>

将创建/删除成本调整系数设置为 <percent>。默认为 60。如果 git range-diff 错误地将较大的更改视为完全重写（删除一个提交并添加另一个），请尝试较大的值，反之则尝试较小的值。有关为什么需要此参数的说明，请参阅下方的“算法”部分。

--left-only

隐藏第一个指定范围（或使用 <rev1>...<rev2> 格式时的“左侧范围”）中缺失的提交。

--right-only

隐藏第二个指定范围（或使用 <rev1>...<rev2> 格式时的“右侧范围”）中缺失的提交。

--diff-merges=<format>

不再忽略合并提交，而是使用 git-log[1] 的相应 --diff-merges=<format> 选项为它们生成差异，并将它们包含在比较中。

注意：在常见情况下，remerge 模式是最自然的选择，因为它仅显示在 Git 合并机制所产生结果之上的差异。换句话说，如果一个合并提交是无冲突 git merge 的结果，remerge 模式将用空差异来表示它。

--remerge-diff

便捷选项，等同于 --diff-merges=remerge。

--notes[=<ref>]
--no-notes

此标志会传递给生成补丁的 git log 程序（参见 git-log[1]）。

<range1> <range2>

比较两个范围指定的提交，其中 <range1> 被认为是 <range2> 的旧版本。

<rev1>…​<rev2>

等同于传入 <rev2>..<rev1> 和 <rev1>..<rev2>。

<base> <rev1> <rev2>

等同于传入 <base>..<rev1> 和 <base>..<rev2>。请注意，<base> 不需要是分支的确切分叉点。示例：在变基分支 my-topic 后，git range-diff my-topic@{u} my-topic@{1} my-topic 将显示变基引入的差异。

git range-diff 还接受常规的 diff 选项（参见 git-diff[1]），最显著的是 --color=[<when>] 和 --no-color 选项。这些选项在生成“补丁之间的差异”时使用，即用于比较对应的新旧提交的作者、提交消息和差异。目前没有办法调整生成这些补丁时传递给 git log 的大部分 diff 选项。

输出稳定性

range-diff 命令的输出可能会发生变化。它旨在作为人类可读的展示性输出，而不是用于跨 Git 版本获取文本上稳定的 range-diff 的工具（与 git-patch-id[1] 的 --stable 选项不同）。此外，range-diff 没有 git-apply[1] 的等价物，其输出不打算由机器读取。

当传入 diff 选项时尤其如此。目前，一些选项（如 --stat）作为涌现效应，可能会产生在 range-diff 上下文中毫无用处的输出。range-diff 的未来版本可能会学习以特定于 range-diff 的方式解释这些选项（例如，对于 --stat，生成人类可读的总结 diffstat 变更方式的输出）。

配置

此命令使用 diff.color.* 和 pager.range-diff 设置（后者默认开启）。参见 git-config[1]。

示例

当变基需要解决合并冲突时，随后可以使用以下命令直接比较变基引入的变更：

$ git range-diff @{u} @{1} @

git range-diff 的典型输出如下所示：

-:  ------- > 1:  0ddba11 Prepare for the inevitable!
1:  c0debee = 2:  cab005e Add a helpful message at the start
2:  f00dbal ! 3:  decafe1 Describe a bug
    @@ -1,3 +1,3 @@
     Author: A U Thor <author@example.com>

    -TODO: Describe a bug
    +Describe a bug
    @@ -324,5 +324,6
      This is expected.

    -+What is unexpected is that it will also crash.
    ++Unexpectedly, it also crashes. This is a bug, and the jury is
    ++still out there how to fix it best. See ticket #314 for details.

      Contact
3:  bedead < -:  ------- TO-UNDO

在这个例子中，有 3 个旧提交和 3 个新提交，开发者删除了第 3 个提交，在前两个提交之前添加了一个新提交，并修改了第 2 个提交的提交消息及其差异。

当输出到终端时，默认会进行颜色编码，就像常规的 git diff 输出一样。此外，第一行（添加提交）为绿色，最后一行（删除提交）为红色，第二行（完美匹配）为黄色（类似于 git show 输出的提交标题），第三行将旧提交着色为红色，新提交着色为绿色，其余部分则像 git show 的提交标题一样着色。

然而，实际上，原始的彩色差异对比很难阅读，因为它会将整行着色为红色或绿色。例如，旧提交中添加“What is unexpected”的行是完全红色的，即使旧提交的意图是添加某些内容。

为了解决这个问题，range 默认使用 --dual-color 模式。在此模式下，差异的差异将保留原始差异颜色，并使用背景为红色或绿色的 -/+ 标记作为行前缀，从而使它们更清晰地描述差异本身是如何变化的。

算法

总体思路如下：我们生成两个提交范围中提交之间的成本矩阵，然后解决最小成本分配问题。

成本矩阵的填充方式如下：对于每一对提交，生成两个差异，并生成带有 3 行上下文的“差异的差异”，然后将该差异中的行数用作成本。

为了避免误报（例如，当一个补丁被删除，而在同一个补丁系列的两个迭代之间添加了一个不相关的补丁时），成本矩阵通过添加针对整体删除/添加的固定成本条目进行了扩展。

示例：假设提交 1--2 是补丁系列的第一次迭代，A--C 是第二次迭代。假设 A 是 2 的拣选（cherry-pick），而 C 是 1 的拣选，但有少量修改（比如修正了一个错别字）。将提交可视化为二分图：

    1            A

    2            B

		 C

我们正在寻找一种用旧系列来解释新系列的“最佳”方法。我们可以将“解释”表示为图中的一条边：

    1            A
	       /
    2 --------'  B

		 C

这种解释是“免费”的，因为没有任何变化。同样，C 可以使用 1 来解释，但由于修改，这会有 c>0 的成本。

    1 ----.      A
	  |    /
    2 ----+---'  B
	  |
	  `----- C
	  c>0

用数学术语来说，我们正在寻找某种最小成本二分匹配；1 以一定的成本与 C 匹配，等等。底层图实际上是一个完全二分图；我们与每条边关联的成本是两个提交补丁之间差异的大小。为了也能解释新的提交，我们在双方都引入了虚拟节点。

    1 ----.      A
	  |    /
    2 ----+---'  B
	  |
    o     `----- C
	  c>0
    o            o

    o            o

边 o--C 的成本是 C 差异的大小，并由一个应小于 100% 的调整系数进行修正。边 o--o 的成本是免费的。调整系数是必要的，因为即使 1 和 C 没有任何共同之处，它们可能仍然共享几行空行等，这可能使得 1--C, o--o 的分配比 1--o, o--C 稍微便宜一些，即使 1 和 C 没有任何共同之处。通过调整系数，我们要求有更大的共同部分才将补丁视为对应。

计算此算法所需的总时间是计算 n+m 个提交差异，然后是 n*m 个补丁差异所需的时间，加上计算 n 和 m 个差异之间最小成本分配所需的时间。Git 使用 Jonker-Volgenant 算法的实现来解决分配问题，该算法具有立方运行时复杂度。在这种情况下找到的匹配将如下所示：

    1 ----.      A
	  |    /
    2 ----+---'  B
       .--+-----'
    o -'  `----- C
	  c>0
    o ---------- o

    o ---------- o

另请参阅

git-log[1]

GIT

Git[1] 套件的一部分