管理堆叠式拉取请求

重组堆叠拉取请求，将其分支变基，并使用 GitHub CLI 对较低层进行更改。

在本文中

在补丁栈上迭代时，通常需要在较低层进行更改、变基以保留线性历史记录，或重构其分支。 在 GitHub CLI 中，gh stack 扩展通过级联操作处理这些任务，这些操作会更新每个受影响的分支。 请参阅“堆叠式拉取请求 CLI 命令”。

对较低层进行更改

在顶层上工作时，需要更改堆栈中较低层的内容时，请在其所属的分支中进行更改并重新定基，而不是在当前层中变通处理。

  1. 导航到需要更改的分支。

    Shell
    gh stack down

    还可以使用 切换到特定分支。

  2. 进行更改并提交该更改。

    Shell
    git add .
git commit -m "helpful-commit-message"

  3. 对上述分支执行变基，以包含该更改。

    Shell
    gh stack rebase --upstack

  4. 推送更新后的分支并返回到之前工作的地方。

    Shell
    gh stack push
gh stack top

对你的堆栈进行变基

堆栈必须在其分支之间具有线性历史记录，然后才能被合并。 运行 gh stack rebase 会执行级联 rebase，其中每个分支都会变基到其下方的分支之上，从 main 开始，因此每个分支都会获取所有下层分支的最新更改。

  1. 对堆栈进行变基。 默认情况下，这会将每个分支从底部到顶部依次变基。

    Shell
    gh stack rebase

    若要限制变基，请使用 --downstack 将从最低层到当前分支的提交进行变基，或使用 --upstack 将从当前分支到顶部的提交进行变基。

  2. 推送更新的分支。 这用于通过 --force-with-lease 安全地更新变基后的分支。

    Shell
    gh stack push

如果变基遇到冲突，gh stack rebase 会停止并列出冲突的文件。

  • 解决受影响文件中的冲突标记，使用 git add 将其暂存，然后运行 gh stack rebase --continue。
  • 若要重新开始，请运行 gh stack rebase --abort 以将所有分支还原到变基前的状态。

注意

还可以从拉取请求触发服务器端变基，但这些提交未签名。 如果存储库需要签名提交，请从 GitHub CLI 变基，使这些提交遵循本地 Git 提交签名配置。

从 GitHub 网站变基

当堆栈不线性时，合并框中会显示 Rebase stack 按钮。 选择它会触发服务器端级联 rebase：

  1. 将整个堆栈重新定基在最新主干的顶部，例如 main。
  2. 将每个未合并的分支重新定基到其基分支之上，并从堆栈底部向上依次进行。
  3. 强制推送每个变基后的分支以更新远程。

变基完成后，每个拉取请求都会反映更新的分支，并重新触发 CI 检查。

注意

服务器端变基创建的提交不会被签名。 如果存储库需要签名的提交，请使用gh stack rebase从GitHub CLI开始变基，使提交遵循本地 Git 提交签名配置，然后使用gh stack push推送。

重组堆栈

你可能想要更改堆栈的构成。 例如，如果需要删除分支、合并分支、插入分支、重新排序或重命名，请使用交互式命令 gh stack modify。

在运行 gh stack modify之前，请确保满足以下条件：

  • 您已检出活动堆栈。
  • 工作区没有变更。
  • 当前没有正在进行的变基操作。
  • 当前没有排队等待合并的拉取请求。
  • 提交历史记录是线性的。

  1. 打开终端修改界面。

    Shell
    gh stack modify

  2. 选择分支并将更改加入暂存区。 在同一会话中不能混合重新排序和结构更改（drop、fold、insert、rename）。

    • x — 丢弃分支及其提交
    • d — 将该分支折叠到其下方的分支中
    • u — 将分支合并到其上方的分支中
    • i / I — 在光标下方或上方插入新分支
    • r — 重命名分支
    • Shift+↑ / Shift+↓ — 对分支重新排序
    • z — 撤消最后一个暂存操作

  3. 通过保存应用暂存更改。 在保存之前，不会进行任何修改。

    使用 ctrl/cmd+s。

    如果在应用时发生冲突，请解决此问题并运行 gh stack modify --continue，或运行 gh stack modify --abort 以还原预修改状态。

  4. 推送更新的分支并在 GitHub 上重新创建堆栈。

    Shell
    gh stack submit

从 GitHub 网站取消堆叠

若要从网站取消堆叠，例如重新排序或重新组织堆栈，请使用堆栈上的 Unstack 选项。

取消堆叠会删除堆叠中的 打开、草稿和关闭 拉取请求。 每个分支保留其当前基分支，但不再链接到其他分支，堆栈映射和堆栈合并要求会从它们中消失。

合并的拉取请求和已排队的拉取请求保留在请求栈中。 拉取请求合并或排队进行合并后，作为堆栈的一部分，无法从堆栈中移除。 仅当其拉取请求均未合并或排队进行合并时，堆栈才会完全解散；否则该堆栈仍会保留，且其中仍包含这些拉取请求。

若要在不解散堆栈的情况下重新排序或重构堆栈，请改用 gh stack modify 命令。 请参阅 重新构建堆叠。

合并后同步本地环境

当堆栈底部的拉取请求合并时，请使用单个同步命令更新本地状态。 若要同时自动修剪已合并的拉取请求的本地分支，请添加该 --prune 选项。

Shell
gh stack sync --prune

这会提取最新的更改，将主干快进，将剩余的分支重新基于它，推送更新的分支，并从 GitHub 同步拉取请求状态。

将添加到堆栈上的拉取请求纳入 GitHub

如果其他人将拉取请求添加到堆栈上 GitHub，gh stack sync 则提取新分支并将其追加到本地堆栈，使其与远程保持一致。 此类干净的远端领先更新会被自动拉取，因此 gh stack sync 可以安全地在自动化中运行。

解决发生分歧的堆栈

当两个堆栈都不是另一个的干净扩展时，本地堆栈和远程堆栈就会发生分叉，例如，当你在本地添加分支，而在 GitHub 上向同一堆栈添加了不同的拉取请求时。 发生这种情况时， gh stack sync 无法自动合并这两者。 在交互式终端中，它提供了三种选择：

  • 使用远程堆栈作为事实来源。 将本地栈配置替换为远程的，并拉取所有缺失的分支。 如果你所在的分支已不在远程堆栈中，则你会被移到最近仍保留的分支。 这需要一个干净的工作树，没有未提交的更改。
  • 在GitHub上删除堆栈。 删除 GitHub 上的 stack 对象并停止同步。拉取请求和本地分支保持不变。 使用 gh stack submit 重新创建堆栈，该操作还会为任何尚未提交为拉取请求的分支创建拉取请求。 如果要更改其结构，请首先运行 gh stack modify 。
  • 取消。 在不推送分支或更新任何拉取请求的情况下中止同步。

在非交互式终端（如 CI）中，出现分歧时，同步会中止，而不会推送分支或更新拉取请求。 通过解除堆叠并重新创建堆栈来解决此问题。

后续步骤