git-rebase - 在另一个基端之上重新应用提交

将一系列提交移植到不同的起点。你也可以使用 git rebase 来重新排序或合并提交：请参阅下文的“交互模式”了解如何操作。

例如，假设你一直在历史中的 topic 分支上工作，并且你想“赶上” master 分支上完成的工作。

你想将你在 topic 分支自偏离 master 以来所做的提交（即 A、B 和 C）移植到当前 master 的顶部。你可以在检出 topic 分支时运行 git rebase master 来实现。如果你想在其他分支上变基 topic，git rebase master topic 是 git checkout topic && git rebase master 的快捷方式。

如果在此过程中发生合并冲突，git rebase 将停止在第一个有问题提交处并留下冲突标记。如果发生这种情况，你可以执行以下操作之一：

如果你没有指定变基到的 <upstream>（上游），将使用 branch.<name>.remote 和 branch.<name>.merge 选项中配置的上游（详见 git-config[1]），并假定使用 --fork-point 选项。如果你当前不在任何分支上，或者当前分支没有配置上游，变基将中止。

以下是 git rebase <upstream> 所做工作的简化描述：

以下是如何使用 rebase --onto 将基于一个分支的主题分支移植到另一个分支，从而模拟你从后者分支派生了该主题分支。

首先，假设你的 topic 基于 next 分支。例如，在 topic 中开发的一个功能依赖于 next 中的某些功能。

我们想让 topic 改为从 master 分支派生；例如，因为 topic 所依赖的功能已被合并到更稳定的 master 分支中。我们希望我们的树看起来像这样：

我们可以使用以下命令实现：

--onto 选项的另一个例子是变基分支的一部分。如果我们有以下情况：

那么命令

将导致

这在 topicB 不依赖于 topicA 时非常有用。

变基也可以删除一系列提交。如果我们有以下情况：

那么命令

将导致提交 F 和 G 被删除

如果 F 和 G 存在某种缺陷，或者不应成为 topicA 的一部分，这很有用。请注意，--onto 的参数和 <upstream> 参数可以是任何有效的提交对象（commit-ish）。

本节中的选项不能与任何其他选项一起使用，彼此之间也不能混用：

有关示例，请参阅上面的“使用 --ONTO 迁移主题分支”。

以下选项：

与以下选项不兼容：

此外，以下成对选项不兼容：

git rebase 有两个主要的后端：apply 和 merge。（apply 后端以前被称为 am 后端，但该名称容易引起混淆，因为它看起来像动词而不是名词。此外，merge 后端以前被称为交互式后端，但现在它也用于非交互式情况。两者都根据支撑各自的底层功能进行了重命名。）这两个后端的行为方式有一些细微的差异：

合并机制（git merge 和 git pull 命令）允许使用 -s 选项选择后端合并策略。一些策略还可以接受自己的选项，这些选项可以通过向 git merge 和/或 git pull 传递 -X<option> 参数来传递。

在使用三向合并（包括默认的 ort）的策略中，如果在两个分支上都进行了更改，但之后在一个分支上撤销了该更改，那么该更改将保留在合并结果中；有些人认为这种行为令人困惑。这是因为在执行合并时，只考虑了头和合并基，而没有考虑单个提交。因此，合并算法将撤销的更改视为没有更改，而是用更改后的版本替换。

你应该了解在共享仓库上使用 git rebase 的后果。另请参阅下文的“从上游变基中恢复”。

运行变基时，如果存在 pre-rebase 钩子，它将首先执行。你可以使用此钩子进行完整性检查，如果不合适则拒绝变基。请参阅 pre-rebase 钩子脚本模板作为示例。

完成后，<branch> 将成为当前分支。

以交互方式变基意味着你有机会编辑正在变基的提交。你可以重新排序提交，也可以删除它们（剔除坏的或不需要的补丁）。

交互模式适用于此类工作流程：

其中第 2 点包含以下情况的多次实例：

a) 常规使用

b) 独立修复

有时在 b.2 中修复的内容无法直接通过 amend 合并到它所修复的不太完美的提交中，因为该提交深埋在补丁系列中。这正是交互式变基的用途：在进行大量 "a" 和 "b" 之后使用它，通过重新排列和编辑提交，以及将多个提交压缩为一个。

以你想保留原样的最后一个提交作为起点启动：

编辑器将启动，其中包含当前分支中在给定提交之后的所有提交（忽略合并提交）。你可以根据心愿重新排序此列表中的提交，也可以删除它们。列表看起来大概是这样的：

单行描述纯粹是为了方便你查看；git rebase 不会查看它们，而是查看提交名称（本例中为 "deadbee" 和 "fa1afe1"），因此请勿删除或编辑提交名称。

通过将命令 "pick" 替换为 "edit"，你可以告诉 git rebase 在应用该提交后停止，以便你可以编辑文件和/或提交消息，修改提交，然后继续变基。

要中断变基（就像 "edit" 命令所做的那样，但不先拣选任何提交），请使用 "break" 命令。

如果你只想编辑某个提交的提交消息，请将命令 "pick" 替换为 "reword"。

要丢弃提交，请将命令 "pick" 替换为 "drop"，或者直接删除对应的行。

如果你想将两个或多个提交合并为一个，请将第二个及后续提交的 "pick" 命令替换为 "squash" 或 "fixup"。如果提交有不同的作者，合并后的提交将归功于第一个提交的作者。合并提交的建议提交消息是第一个提交的消息与标有 "squash" 命令的消息的串联，省略标有 "fixup" 命令的消息，除非使用了 "fixup -c"。在这种情况下，建议的提交消息仅为 "fixup -c" 提交的消息，并会打开编辑器允许你编辑消息。"fixup -c" 提交的内容（补丁）仍会合并到折叠后的提交中。如果有多个 "fixup -c" 提交，则使用最后一个提交的消息。你也可以使用 "fixup -C" 来获得与 "fixup -c" 相同的行为，只是不打开编辑器。

当 "pick" 被替换为 "edit" 或命令由于合并错误而失败时，git rebase 将停止。完成编辑和/或解决冲突后，你可以使用 git rebase --continue 继续。

例如，如果你想重新排序最后 5 个提交，使得原本的 HEAD~4 成为新的 HEAD。为此，你可以像这样调用 git rebase：

并将第一个补丁移动到列表末尾。

你可能想要重新创建合并提交，例如，如果你有这样的历史：

假设你想将从 "A" 开始的分支变基到 "Q"。确保当前 HEAD 是 "B"，并调用：

重新排序和编辑提交通常会产生未经测试的中间步骤。你可能希望通过运行测试来检查历史编辑是否破坏了任何内容，或者至少通过使用 "exec" 命令（快捷键 "x"）在历史的中间点重新编译。你可以通过创建如下所示的待办事项列表来实现：

当命令失败（即以非 0 状态退出）时，交互式变基将停止，给你修复问题的机会。你可以使用 git rebase --continue 继续。

"exec" 命令在 shell（默认为 /bin/sh）中启动命令，因此你可以使用 shell 功能（如 "cd"、">"、";" …）。该命令在工作树的根目录下运行。

此命令可让你检查中间提交是否可编译。待办事项列表如下所示：

在交互模式下，你可以用 "edit" 操作标记提交。但是，这并不一定意味着 git rebase 期望这次编辑的结果恰好是一个提交。实际上，你可以撤销该提交，或者添加其他提交。这可以用来将一个提交拆分为两个：

如果你不能绝对确定中间版本是一致的（它们能编译、通过测试套件等），你应该在每次提交后使用 git stash 暂存尚未提交的更改，进行测试，并在必要时修改提交。

变基（或任何其他形式的改写）一个他人已基于其开展工作的分支是个坏主意：下游的任何人都被迫手动修复他们的历史。本节解释了如何从下游的角度进行修复。然而，真正的修复方法应该是首先避免变基上游分支。

为了说明，假设某人开发了一个 subsystem（子系统）分支，而你正在开发一个依赖于此 subsystem 的 topic（主题）。你最终可能会得到如下所示的历史：

如果 subsystem 针对 master 进行了变基，会发生以下情况：

如果你现在照常继续开发，并最终将 topic 合并到 subsystem，那么来自 subsystem 的提交将永远重复存在：

此类重复提交通常是不受欢迎的，因为它们会扰乱历史，使其难以追踪。为了清理，你需要将 topic 上的提交移植到新的 subsystem 末端，即变基 topic。这会产生连锁反应：topic 的任何下游也都不得不变基，以此类推！

有两种修复方法，在以下小节中讨论：

交互式变基命令最初是为处理单个补丁系列而设计的。因此，将合并提交从待办事项列表中排除是有道理的，因为开发者可能在分支工作期间合并了当时的 master，只是为了最终将所有提交变基到 master 上（跳过合并提交）。

但是，开发者可能有正当理由想要重新创建合并提交：在处理多个相互关联的分支时保持分支结构（或“提交拓扑”）。

在以下示例中，开发者在一个主题分支上重构按钮的定义方式，并在另一个主题分支上使用该重构来实现“报告错误”按钮。git log --graph --format=%s -5 的输出可能如下所示：

开发者可能希望将这些提交变基到较新的 master，同时保持分支拓扑。例如，当第一个主题分支预计比第二个更早集成到 master 时，以此解决与进入 master 的 DownloadButton 类更改产生的合并冲突。

此变基可以使用 --rebase-merges 选项执行。它将生成如下所示的待办事项列表：

与常规交互式变基不同，除了 pick 命令外，还有 label、reset 和 merge 命令。

label 命令在执行时将一个标签与当前 HEAD 关联。这些标签作为工作树本地引用（refs/rewritten/<label>）创建，并在变基完成时删除。这样，链接到同一仓库的多个工作树中的变基操作就不会相互干扰。如果 label 命令失败，它会立即重新调度，并显示有关如何继续的有用消息。

reset 命令将 HEAD、索引和工作树重置为指定的修订版本。它类似于 exec git reset --hard <label>，但拒绝覆盖未跟踪的文件。如果 reset 命令失败，它会立即重新调度，并显示有关如何编辑待办事项列表的有用消息（这通常发生在手动在待办事项列表中插入了包含拼写错误的 reset 命令时）。

merge 命令将指定的修订版本合并到当时的 HEAD 中。配合 -C <original-commit>，将使用指定合并提交的提交消息。当 -C 更改为小写 -c 时，合并成功后将在编辑器中打开消息，以便用户编辑。

如果 merge 命令由于合并冲突以外的任何原因失败（即合并操作甚至没有开始），它会立即重新调度。

默认情况下，merge 命令将对常规合并使用 ort 合并策略，对章鱼合并（octopus merge）使用 octopus 策略。调用 rebase 时可以使用 --strategy 参数为所有合并指定默认策略，也可以在交互式命令列表中通过使用 exec 命令显式调用带有 --strategy 参数的 git merge 来覆盖特定合并。请注意，当像这样显式调用 git merge 时，你可以利用标签是工作树本地引用这一事实（例如，引用 refs/rewritten/onto 将对应于标签 onto），以便引用你想合并的分支。

注意：第一个命令（label onto）标记了提交变基到的修订版本；名称 onto 只是一个约定，旨在向 --onto 选项致敬。

还可以通过添加 merge <merge-head> 形式的命令来从头开始引入全新的合并提交。此形式将生成一个初步的提交消息，并始终打开编辑器让用户编辑。例如，当一个主题分支结果证明解决了多个问题，并希望被拆分为两个甚至更多主题分支时，这很有用。考虑这个待办事项列表：

此列表中与 CMake 无关的那次提交很可能是由于修复由切换到 CMake 引入的所有错误而产生的，但它解决的是不同的问题。要将此分支拆分为两个主题分支，可以将待办事项列表修改如下：

本节中以下所有内容均从 git-config[1] 文档中选择性地包含。内容与彼处相同：

Git[1] 套件的一部分