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

如果指定了 <branch>，git rebase 将在执行任何其他操作之前自动执行 git switch <branch>。否则它将保留在当前分支上。

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

当前分支中所有由提交所做的更改，但不在 <upstream> 中的更改将被保存到一个临时区域。这与 git log <upstream>..HEAD 所显示的提交集相同；或者如果 --fork-point 处于活动状态，则由 git log 'fork_point'..HEAD 显示的提交集相同（请参阅下面关于 --fork-point 的描述）；或者如果指定了 --root 选项，则由 git log HEAD 显示的提交集相同。

当前分支将重置为 <upstream> 或 <newbase>（如果提供了 --onto 选项）。这与 git reset --hard <upstream>（或 <newbase>）的效果完全相同。ORIG_HEAD 被设置为指向重置之前分支的顶端。

然后，之前保存到临时区域的提交将按顺序逐个重新应用于当前分支。请注意，HEAD 中任何引入与 HEAD..<upstream> 中提交相同文本更改的提交都将被忽略（即，如果一个补丁已经在 upstream 中接受，但具有不同的提交信息或时间戳，则它将被跳过）。

合并失败可能会阻止此过程完全自动完成。你必须解决任何此类合并失败，并运行 git rebase --continue。另一个选择是使用 git rebase --skip 跳过导致合并失败的提交。要检出原始的 <branch> 并删除 .git/rebase-apply 工作文件，请使用命令 git rebase --abort。

假设存在以下历史记录，并且当前分支为“topic”

从这一点来看，以下任一命令的结果

将是

注意： 后一种形式只是 git checkout topic 后跟 git rebase master 的简写形式。当变基退出时，topic 将仍然是已检出分支。

如果上游分支已经包含你所做的更改（例如，因为你发送了一个在 upstream 应用的补丁），那么该提交将被跳过，并将发出警告（如果使用 merge 后端）。例如，在以下历史记录中运行 git rebase master（其中 A' 和 A 引入了相同的一组更改，但具有不同的提交者信息）

将导致

以下是如何使用 rebase --onto 将基于一个分支的主题分支移植到另一个分支，以假装你从后一个分支分叉了主题分支。

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

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

我们可以使用以下命令来实现这一点

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

那么命令

将导致

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

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

那么命令

将导致删除提交 F 和 G

这在 F 和 G 有缺陷或不应该作为 topicA 的一部分时很有用。请注意，--onto 的参数和 <upstream> 参数可以是任何有效的提交标识符。

如果发生冲突，git rebase 将在第一个有问题的提交处停止，并在树中留下冲突标记。你可以使用 git diff 来查找标记（<<<<<<），并进行编辑以解决冲突。对于你编辑的每个文件，你需要告诉 Git 冲突已解决，通常可以通过以下方式完成

手动解决冲突并使用所需的解决方案更新索引后，你可以使用以下命令继续变基过程

或者，你可以使用以下命令撤消 git rebase

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

以下选项

与以下选项不兼容

此外，以下选项对不兼容

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 中修复的内容无法修补到它修复的并不完美的提交，因为该提交深埋在一个补丁系列中。这正是交互式变基的用途：在大量“a”和“b”之后使用它，通过重新排列和编辑提交，并将多个提交压缩为一个。

从您要保留为原样的最后一个提交开始

将启动一个编辑器，其中包含当前分支中的所有提交（忽略合并提交），这些提交位于给定提交之后。您可以在此列表中随意重新排序提交，也可以删除它们。列表看起来或多或少是这样的

单行描述纯粹是为了您的享受；git rebase 不会查看它们，而是查看提交名称（在本例中为“deadbee”和“fa1afe1”），因此不要删除或编辑这些名称。

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

要中断变基（就像“edit”命令一样，但首先不执行任何 cherry-picking 操作），请使用“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（默认 shell，通常为 /bin/sh）中启动命令，因此您可以使用 shell 功能（如“cd”、“>”、”;" 等）。该命令从工作树的根目录运行。

此命令允许您检查中间提交是否可编译。待办事项列表将变为这样

在交互模式下，您可以用操作“edit”标记提交。但是，这并不一定意味着 git rebase 期望此编辑的结果正好是一个提交。实际上，您可以撤消提交，也可以添加其他提交。这可以用来将提交拆分为两个

如果您不能完全确定中间修订版是否一致（它们可以编译、通过测试套件等），您应该在每次提交后使用 git stash 来存储尚未提交的更改，测试，并在必要时修改提交。

变基（或任何其他形式的重写）他人已基于其工作的分支是一个坏主意：所有下游用户都必须手动修复其历史记录。本节解释如何从下游的角度进行修复。然而，真正的修复方法是首先避免在上游进行变基。

为了说明，假设您处于有人开发 子系统 分支，而您正在开发一个依赖于此 子系统 的 主题 的情况。您最终可能会得到以下历史记录

如果 子系统 相对于 master 进行变基，将会发生以下情况

如果您现在像往常一样继续开发，并最终将 主题 合并到 子系统，来自 子系统 的提交将永远保持重复

此类重复通常不被接受，因为它们会使历史记录混乱，难以追踪。为了清理这些内容，您需要将 主题 上的提交移植到新的 子系统 顶端，即变基 主题。这会产生连锁反应：所有 主题 的下游用户都必须进行变基，以此类推！

存在两种类型的修复，将在以下小节中讨论

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

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

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

开发人员可能希望将这些提交变基到更新的 master 上，同时保持分支拓扑结构，例如，当第一个主题分支预计比第二个主题分支更早集成到 master 中时，例如，为了解决与对 DownloadButton 类所做的更改的合并冲突，这些更改已进入 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 <original-commit> 时，将使用指定的合并提交的提交消息。当 -C 更改为小写 -c 时，将在成功合并后在编辑器中打开消息，以便用户可以编辑消息。

如果 merge 命令因任何原因（除了合并冲突之外，即当合并操作甚至没有开始时）失败，它将立即重新安排。

默认情况下，merge 命令将对常规合并使用 ort 合并策略，对章鱼合并使用 octopus。可以使用在调用变基时使用 --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] 套件的一部分