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 将显示的相同提交集；或者通过 git log 'fork_point'..HEAD，如果 --fork-point 处于活动状态（请参阅以下有关 --fork-point 的说明）；或者通过 git log HEAD，如果指定了 --root 选项。

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

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

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

假设存在以下历史记录，当前分支为“主题”

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

将是

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

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

将导致

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

首先让我们假设你的主题基于分支下一个。例如，在主题中开发的功能依赖于在下一个中找到的一些功能。

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

我们可以使用以下命令获得此内容

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

那么命令

将导致

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

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

那么命令

将导致删除提交 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> 参数来传递。

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

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

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

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

交互式 rebase 意味着您有机会编辑正在 rebase 的提交。您可以重新排列提交，也可以删除它们（清除不良或不需要的补丁）。

交互模式适用于此类工作流

其中第 2 点包含以下几个实例

a) 常规使用

b) 独立修复

有时，b.2 中修复的内容无法修改为它修复的不太完美的提交，因为该提交深深地埋藏在一个补丁系列中。这正是交互式 rebase 的用途：在大量“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 在每次提交、测试后隐藏尚未提交的更改，并在必要时修改提交。

变基（或任何其他形式的重写）一个其他人基于其工作的分支是一个坏主意：它下游的任何人都被迫手动修复他们的历史记录。本节说明如何从下游的角度进行修复。然而，真正的修复方法是首先避免变基上游。

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

如果子系统针对主系统进行变基，则会发生以下情况

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

通常不赞成此类重复，因为它们会使历史记录变得混乱，从而更难跟踪。要清理内容，您需要将主题上的提交移植到新的子系统提示，即变基主题。这会产生连锁反应：主题下游的任何人都被迫也进行变基，依此类推！

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

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

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

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

开发人员可能希望将这些提交重新设定到较新的master，同时保持分支拓扑，例如，当第一个主题分支预计比第二个主题分支更早集成到master中时，比如说，为了解决与进入master的 DownloadButton 类的更改的合并冲突。

可以使用 --rebase-merges 选项执行此重新设定。它将生成一个待办事项列表，如下所示

与常规交互式重新设定相比，除了 pick 命令之外，还有 label、reset 和 merge 命令。

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

reset 命令将 HEAD、索引和工作树重置到指定的修订版。它类似于 exec git reset --hard <label>，但拒绝覆盖未跟踪的文件。如果 reset 命令失败，它会立即重新安排，并附有如何编辑待办事项列表的有用消息（这通常发生在 reset 命令被手动插入到待办事项列表中并包含错别字时）。

merge 命令将指定的修订版合并到当时的 HEAD 中。使用 -C <original-commit>，将使用指定的合并提交的提交消息。当 -C 更改为小写的 -c 时，在成功合并后，消息将在编辑器中打开，以便用户可以编辑消息。

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

默认情况下，merge 命令将使用 ort 合并策略进行常规合并，并使用 octopus 进行 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] 套件的一部分