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 处于活动状态（详见下方 --fork-point 的说明），则与 git log fork_point'..HEAD 显示的提交集相同；如果指定了 --root 选项，则与 git log HEAD 显示的提交集相同。

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

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

合并失败可能会阻止此过程完全自动化。您将不得不解决任何此类合并失败并运行 git rebase --continue。另一个选项是使用 git rebase --skip 绕过导致合并失败的提交。要检出原始的 <branch> 并移除 .git/rebase-apply 工作文件，请改用命令 git rebase --abort。

假设存在以下历史，并且当前分支是 "topic"

从这一点开始，以下任一命令的结果将是

会是

注意： 后者只是 git checkout topic 后面跟着 git rebase master 的简写。当变基操作退出时，topic 将保持为已检出分支。

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

将导致

这是您如何将一个基于某个分支的主题分支移植到另一个分支，以假装您是从后者分支派生该主题分支的方法，使用 rebase --onto。

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

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

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

--onto 选项的另一个示例是变基分支的一部分。如果出现以下情况

那么命令

将导致

这在 topicB 不依赖于 topicA 的情况下很有用。

还可以通过 rebase 删除一系列提交。如果出现以下情况

那么命令

将导致删除提交 F 和 G

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

如果发生冲突，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" 命令一样，但无需先拣选任何提交），请使用 "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 中时，比如为了解决与 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 命令显式调用带 --strategy 参数的 git merge 来覆盖交互式命令列表中的特定合并。请注意，当像这样显式调用 git merge 时，你可以利用标签是工作区本地引用（例如，引用 refs/rewritten/onto 将对应于标签 onto）这一事实，以便引用你想要合并的分支。

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

还可以通过添加形式为 merge <merge-head> 的命令来从头引入全新的合并提交。这种形式将生成一个临时提交消息，并始终打开编辑器供用户编辑。这在例如一个主题分支解决了不止一个问题并希望拆分为两个或更多主题分支时会很有用。考虑这个待办列表：

此列表中与 CMake 无关的那次提交很可能是为了修复切换到 CMake 所引入的所有错误而进行的，但它解决了不同的问题。要将此分支拆分为两个主题分支，可以像这样编辑待办列表：

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

Git[1] 套件的一部分