git-rebase - 在另一个基础提示之上重新应用提交内容

将一系列提交移植到不同的起点上。你也可以用 git rebase 对提交重新排序或合并：参见下文 INTERACTIVE MODE 了解如何操作。

例如，假设你在如下历史中的 topic 分支上工作，并希望“追上” master 分支上的工作。

你希望将 topic 自从从 master 分叉以来所做的提交（即 A、B、C）移植到当前 master 之上。你可以在检出 topic 分支时运行 git rebase master 来实现。如果你在另一个分支上想对 topic 进行 rebase，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 选项的另一个示例是重新基点分支的一部分。 如果我们有以下情况：

那么命令

将导致 :

这在主题 B 不依赖于主题 A 的情况下非常有用。

也可以用变基删除一系列提交。 如果我们遇到以下情况 :

那么命令

将导致删除 F 和 G 项：

如果 F 和 G 在某些方面有缺陷，或者不应该是 topicA 的一部分，这一点就很有用。 请注意，--onto 参数和 <upstream> 参数可以是任何有效的提交。

本节中的选项不能与任何其他选项一起使用，包括不能相互使用：

示例参见上文“使用 --onto 移植主题分支”。

下列选项：

与下列选项不兼容：

此外，以下几对选项是不兼容的：

git rebase 有两个主要的后台：‘应用’ 和 ‘合并’（‘应用’ 后台曾被称为 am 后台，但这个名字看起来像动词而非名词，因此引起了混淆）。 此外，‘合并’ 后台曾被称为交互式后台，但现在也用于非交互式情况。 两者都是根据各自的底层功能重新命名的）。这两个后台在行为方式上有一些微妙的区别：

合并机制（ git merge 和 git pull 命令）允许用 -s 选项来选择后端’合并策略'。 一些策略也可以采取自己的选项，可以通过给 git merge 和/或 git pull 的 -X<选项> 参数来传递。

对于使用三方合并的策略（包括默认的 ort 策略），如果在两个分支上都做了修改，但后来在其中一个分支上被撤销，那么这个修改就会出现在合并后的结果中；有些人觉得这种行为令人困惑。 出现这种情况是因为在执行合并时只考虑头部和合并基数，而不是单个提交。 因此，合并算法认为被恢复的修改根本就没有变化，而是用被修改的版本来代替。

您应该了解在共享的仓库中使用 git rebase 的影响。 另请参阅下面的从上游重建中恢复。

在运行变基命令时，如果存在 pre-rebase （变基前）钩子，它会首先执行该钩子。 您可以使用此钩子进行正确性检查，并在不合适时拒绝重置。 有关示例，请参阅模板 pre-rebase（变基前） 钩子脚本。

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

交互式重定向意味着你有机会编辑被重定向的提交。 你可以重新排列提交的顺序，也可以删除它们（剔除坏的或不需要的补丁）。

互动模式就是为这种工作流程设计的：

其中第 2 点由以下几个实例组成

a) 常规使用

b) 独立修复

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

从您希望保留原样的最后一次提交开始：

编辑器会弹出当前分支的所有提交（忽略合并提交），这些提交都在给定提交之后。 你可以随心所欲地调整列表中提交的顺序，也可以删除它们。 列表大致如下：

上线描述纯粹是为了方便您查看；git rebase 不会查看这些描述，只会查看提交名称（本例中为 "deadbee" 和 "fa1afe1"），因此请勿删除或编辑这些名称。

用 "edit" 命令替换 "pick" 命令后，你可以告诉 git rebase 在应用该提交后停止，这样你就可以编辑文件和/或提交信息，修改提交，然后继续重置。

要中断重置（就像 "edit" 命令一样，但不会先选择任何提交），请使用 "break "命令。

如果只想编辑提交信息，请用 "reword" 命令替换 "pick" 命令。

要放弃提交，请用 "drop" 替换 "pick" 命令，或直接删除匹配的行。

如果要将两个或更多提交折叠为一个提交，请用 "squash" 或 "fixup" 代替命令 "pick" 来处理第二个及后续提交。 如果提交的作者不同，折叠后的提交将归属于第一个提交的作者。 除非使用了 "fixup -c" 命令，否则折叠提交的建议提交信息是第一个提交信息与 "squash" 命令确定的提交信息的合并，省略了 "fixup" 命令确定的提交信息。 在这种情况下，建议的提交信息只是 "fixup -c" 提交的信息，而且会打开一个编辑器允许你编辑信息。 "fixup -c" 提交的内容（补丁）仍然包含在折叠提交中。如果有多个 "fixup -c" 提交，则使用最后一个提交的信息。 您也可以使用 "fixup -C" 获得与 "fixup -c" 相同的效果，但不需要打开编辑器。

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

例如，如果您想重新排列最近 5 次提交的顺序，让原来的 HEAD~4 变成新的 HEAD。要做到这一点，可以这样调用 git rebase：

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

例如，如果您有这样的历史记录，您可能需要重新创建合并提交：

假设要将从 "A" 开始的侧分支重置为 "Q"。确保当前的 HEAD 是 "B"，然后调用

重新排序和编辑提交通常会产生未经测试的中间步骤。 您可能想通过运行测试来检查您的历史编辑是否破坏了任何东西，或者至少使用 "exec" 命令（快捷键 "x"）在历史的中间点重新编译。 为此，您可以创建类似这样的待办事项列表：

当命令失败（即以非 0 状态退出）时，交互式变基操作就会停止，以便您有机会解决问题。您可以使用 git rebase --continue 继续。

"exec" 命令在 shell（默认的 shell，通常是/bin/sh）中执行命令，因此可以使用 shell 功能（如 "cd"、">"、";"…​…​）。命令从工作区树的根目录运行。

该命令用于检查中间提交是否可编译。 待办事项列表就会变成这样：

在交互模式下，可以用 "edit"（编辑）来标记提交。 不过，这并不一定意味着 git rebase 希望编辑的结果是一个提交。 事实上，你可以撤销提交，也可以添加其他提交。 这可以用来将一个提交一分为二：

如果不能绝对确定中间修订是一致的（编译、通过 testsuite 等），则应使用 git stash 在每次提交、测试之后，将尚未提交的改动保存起来，并在必要时修改提交。

变基（或以任何其他形式改写）他人基于其工作的分支是个坏主意：其下游的任何人都不得不手动修正自己的历史。 本节将从下游的角度解释如何进行修复。 不过，真正的修复方法是首先避免重置上游分支。

举例说明，假设有人开发了一个 ‘子系统’ 分支，而你正在开发一个依赖于该 ‘子系统’ 的 ‘主题’。 你可能会有如下的历史记录：

如果 ‘子系统’ 针对 master 进行重定向，会出现以下情况：

如果现在像往常一样继续开发，并最终将 ‘主题’ 合并到 ‘子系统’，那么 ‘子系统’ 中的提交将永远重复：

这种重复通常是不受欢迎的，因为它们会使历史记录变得杂乱无章，难以跟踪。 要清理这些重复提交，就需要将 ‘主题’ 上的提交移植到新的 ‘子系统’ tip 上，即重置 ‘主题’。 这就会产生连锁反应：‘主题’ 的任何下游提交都会被迫重置，依此类推！

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

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

不过，开发人员想要重新创建合并提交也有合理的原因：在多个相互关联的分支上工作时，为了保持分支结构（或 “提交拓扑”）。

在下面的示例中，开发人员在一个重构了按钮定义方式的特性分支上工作，并在另一个特性分支上使用重构实现了 “报告错误” 按钮。git log --graph --format=%s -5 的输出可能是这样的：

开发人员可能希望在保留分支拓扑的同时，将这些提交重定向到更新的 master 分支，例如，当第一个特性分支比第二个分支更早集成到 master 分支时，开发人员可能希望解决与 “下载按钮” 类的合并冲突，因为 “下载按钮” 类已经集成到了 master 分支。

可以使用 --rebase-merges 选项进行重置。 它将生成如下的待办事项列表：

与常规的交互式变基不同，除了 pick（选取）命令外，还有 label（标签）、reset（重置） 和 merge（合并） 命令。

label 命令会在执行该命令时将一个标签与当前 HEAD 关联。这些标签被创建为工作区本地引用（refs/rewritten/<label>），并将在重置完成后被删除。这样，链接到同一仓库的多个工作区中的重置操作就不会相互干扰。如果 label 命令失败，会立即重新安排，并给出如何继续的提示信息。

reset 命令会将 HEAD、索引和工作区重置为指定的版本。它类似于 exec git reset --hard <label>，但拒绝覆盖未跟踪的文件。如果 reset 命令失败，会立即重新安排，并附带如何编辑待办事项列表的提示信息（这种情况通常发生在 reset 命令被手动插入待办事项列表且包含错字的情况下）。

merge（合并）命令会将指定的版本合并到当时的 HEAD 中。使用 -C <源提交> 时，将使用指定合并提交的提交信息。如果将 -C 改为小写的 -c，合并成功后，提交信息将在编辑器中打开，以便用户编辑信息。

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

默认情况下，merge（合并）命令将对常规合并使用 ort ` 合并策略，对多路合并使用 `octopus 合并策略。 我们可以在调用变基命令时使用 --strategy 参数为所有合并指定一个默认策略，也可以在交互式命令列表中使用 exec 命令显式地调用 git merge 并加上 --strategy 参数来覆盖特定的合并策略。 需要注意的是，像这样显式调用 git merge 时，可以利用标签是工作区本地引用（例如，引用 refs/rewritten/onto 将对应标签 onto）这一事实来引用要合并的分支。

注意：第一条命令（label onto）会标注提交所基于的修订版本；onto ` 只是一个约定俗成的名称，是对 `--onto 选项的一种提示。

也可以通过添加 merge <合并起点> 命令，从头开始引入全新的合并提交。这种形式会生成暂定提交信息，并始终打开编辑器让用户编辑。例如，当一个特性分支要解决的问题不止一个，需要拆分成两个甚至更多特性分支时，这个命令就很有用。请看这个待办事项列表：

该列表中与 CMake 无关的一个提交很可能是为了修复所有因改用 CMake 而引入的错误，但它解决的是另一个问题。要把这个分支分成两个主题分支，可以这样编辑待办事项列表：

本节中这一行以下的内容都是从 git-config[1] 文档中摘录的。其内容与那里的内容相同：

属于 git[1] 文档