git-rebase - 将提交应用到另一个基本提示之上

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

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

当前分支中的所有更改，但不在 <upstream> 中的更改，都将保存到临时区域。 这是与 git log <upstream>..HEAD 相同的提交集合； 或者，如果 --fork-point 处于活动状态，则由 git log 'fork_point'..HEAD 显示（请参阅下面关于 --fork-point 的描述）； 或者，如果指定了 --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 的简写形式。 当 rebase 退出时，topic 将仍然是检出的分支。

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

将导致

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

首先，让我们假设你的 *topic* 基于分支 *next*。 例如，在 *topic* 中开发的功能依赖于 *next* 中找到的某些功能。

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

我们可以使用以下命令获得此结果

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

然后命令

将导致

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

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

然后命令

将导致删除提交 F 和 G

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

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

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

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

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

以下选项

与以下选项不兼容

此外，以下选项对不兼容

git rebase 有两个主要后端：apply 和 merge。 （apply 后端过去被称为 am 后端，但该名称容易混淆，因为它看起来像一个动词而不是名词。此外，merge 后端过去被称为交互式后端，但它现在也用于非交互式的情况。两者都根据支持每个后端较低级别的功能进行了重命名。）这两个后端在行为上存在一些细微的差异

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

对于使用 3 向合并的策略（包括默认的 ort），如果在两个分支上都进行了更改，但后来在一个分支上还原了该更改，则该更改将存在于合并结果中；有些人发现这种行为令人困惑。发生这种情况是因为在执行合并时仅考虑头和合并基础，而不考虑各个提交。因此，合并算法将还原的更改视为根本没有更改，而是替换为已更改的版本。

您应该了解在您共享的存储库上使用 git rebase 的影响。另请参见下面的从上游变基恢复。

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

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

以交互方式变基意味着您有机会编辑要变基的提交。您可以对提交进行重新排序，并且可以删除它们（剔除错误的或不需要的补丁）。

交互模式适用于以下类型的工作流程

其中第 2 点包含几个实例

a) 常规使用

b) 独立修复

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

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

会启动一个编辑器，其中包含当前分支中的所有提交（忽略合并提交），这些提交位于给定提交之后。您可以随意重新排列此列表中的提交，也可以删除它们。该列表大致如下所示：

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

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

要中断变基（就像 "edit" 命令一样，但不会首先 cherry-pick 任何提交），请使用 "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 在每次提交后存储尚未提交的更改，进行测试，并在需要修复时修改提交。

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

为了说明，假设您处于有人开发 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 策略。 可以通过在调用 rebase 时使用 --strategy 参数为所有合并指定默认策略，或者可以通过使用 exec 命令显式调用带有 --strategy 参数的 git merge 来覆盖交互式命令列表中的特定合并。 请注意，像这样显式调用 git merge 时，你可以利用标签是工作区本地引用这一事实（例如，引用 refs/rewritten/onto 对应于标签 onto），以便引用要合并的分支。

注意：第一个命令 (label onto) 标记提交被 rebase 到的修订版本；名称 onto 只是一个约定，以致敬 --onto 选项。

还可以通过添加 merge <merge-head> 形式的命令，从头开始引入全新的合并提交。 此形式将生成一个试探性的提交消息，并且始终打开一个编辑器让用户编辑它。 例如，当一个主题分支最终要解决的不仅仅是一个问题，而是想拆分成两个甚至更多主题分支时，这可能很有用。 考虑以下待办事项列表

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

本节中此行下面的所有内容都是从 git-config[1] 文档中有选择地包含的。 内容与那里找到的内容相同

属于 git[1] 套件的一部分