git-rebase - 在另一个基点之上重放提交

将一系列提交移植到另一个起点。您也可以使用 git rebase 来重新排序或合并提交：有关如何操作，请参见下面的交互模式。

例如，假设您一直在处理此历史中的 topic 分支，并且您想“跟上”在 master 分支上完成的工作。

您想将您自 topic 从 master 分叉以来所做的提交（即 A、B 和 C）移植到当前的 master 之上。您可以通过在签出 topic 分支时运行 git rebase master 来实现。如果您想在其他分支上 rebase topic，git rebase master topic 是 git checkout topic && git rebase master 的快捷方式。

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

如果您没有指定要 rebase 的 <upstream>，则将使用在 branch.<name>.remote 和 branch.<name>.merge 选项中配置的上游（有关详细信息，请参阅 git-config[1]），并且假定使用 --fork-point 选项。如果您当前不在任何分支上，或者当前分支没有配置的上游，则 rebase 将中止。

以下是 git rebase <upstream> 执行操作的简化描述：

这是使用 rebase --onto 将基于一个分支的主题分支移植到另一个分支的方法，假装您从后者分支分叉了主题分支。

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

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

我们可以使用以下命令来实现此目的：

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

那么命令：

将导致：

当 topicB 不依赖于 topicA 时，这很有用。

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

那么命令：

将导致删除提交 F 和 G：

如果 F 和 G 有缺陷，或者不应成为 topicA 的一部分，这会很有用。请注意，--onto 的参数和 <upstream> 参数可以是任何有效的 commit-ish。

本节中的选项不能与其他任何选项一起使用，包括它们本身也不能互相使用。

有关示例，请参阅上面的 TRANSPLANTING A TOPIC BRANCH WITH --ONTO。

以下选项：

与以下选项不兼容：

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

git rebase 有两个主要后端：apply 和 merge。（apply 后端以前称为 am 后端，但名称会引起混淆，因为它看起来像动词而不是名词。此外，merge 后端以前称为交互式后端，但现在也用于非交互式场景。两者都基于支撑它们的底层功能进行了重命名。）这两种后端在行为上存在一些细微的差异：

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

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

您应该了解在共享的存储库上使用git rebase的含义。另请参阅下面的“从上游rebase恢复”。

运行变基时，它将首先执行pre-rebase钩子（如果存在）。您可以使用此钩子进行健全性检查，如果变基不合适，则拒绝变基。请参阅模板pre-rebase钩子脚本以获取示例。

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

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

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

其中第2点包含多个实例：

a)常规使用

b)独立的修复

有时，在b.2中修复的东西无法附加到它所修复的、并非完美无缺的提交中，因为该提交深埋在补丁系列中。这正是交互式变基的用途：在进行了大量“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”相同的行为，只是不打开编辑器。

git rebase会在“pick”被替换为“edit”时停止，或者当命令由于合并错误而失败时停止。当您完成编辑和/或解决冲突后，可以继续使用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期望此编辑的结果正好是一个提交。事实上，您可以撤销该提交，或者添加其他提交。这可以用于将一个提交拆分成两个。

如果您不确定中间修订是否一致（它们可以编译、通过测试套件等），您应该使用git stash将尚未提交的更改暂存起来，进行测试，并在必要时修复并修改提交。

对他人已在其基础上进行开发的某个分支进行变基（或其他形式的重写）是一个坏主意：任何下游的都将被迫手动修复其历史记录。本节从下游的角度解释如何进行修复。然而，真正的修复是避免最初对上游进行变基。

举例来说，假设您处于这样一种情况：有人开发了一个子系统分支，而您正在处理一个依赖于该子系统的主题。您可能会得到如下历史记录：

如果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进行八爪合并。可以通过在调用rebase时使用--strategy参数来为所有合并指定默认策略，或者可以通过在命令的交互式列表中使用exec命令显式调用git merge并带有--strategy参数来覆盖特定的合并。请注意，当显式调用git merge时，您可以利用标签是工作树本地引用的事实（例如，引用refs/rewritten/onto将对应于标签onto），以便引用您要合并的分支。

注意：第一个命令（label onto）标记变基提交所在的修订；onto这个名字只是一个约定，是为了呼应--onto选项。

也可以通过添加形式为merge <merge-head>的命令来创建全新的合并提交。这种形式将生成一个暂定提交消息，并始终打开编辑器让用户编辑。这在例如主题分支被发现涉及多个问题，并希望被拆分成两个或更多主题分支时很有用。考虑这个待办事项列表：

此列表中与CMake无关的提交可能就是因为处理CMake引入的所有错误而产生的，但它解决了不同的问题。要将此分支拆分成两个主题分支，可以像这样编辑待办事项列表：

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

Git[1] 套件的一部分