如何使用 gh-stack 摆脱庞大的 Pull Request 困境

我们都有过这样的经历：你正在开发一个涉及 API、后端逻辑和前端的复杂功能。结果就是产生一个包含三千行代码的巨大 PR。审查者打开它，看到如此庞大的代码量，默默叹了口气，然后关掉标签页等待更好的时机。或者更糟，五分钟就草草浏览完，写下"LGTM"，错过了关键性 bug。

为了不折磨同事，我们尝试把改动拆分成小块。但随后依赖地狱开始了：分支 feature-ui 依赖于 feature-api，而 feature-api 又依赖于 feature-db。修复链底部的某个问题，你就得手动变基所有上层分支，在 GitHub 上追踪基础分支，还得祈祷一切顺利。

看来 GitHub 的工程师们也受够了这个问题，于是为他们的 CLI 发布了一个扩展——gh-stack。它可以自动处理所谓的"堆叠式"pull request。

什么是堆叠式 PR，为什么你需要它们

原理很简单：不要一次性提交一个巨大的改动，而是创建一系列小的、逻辑上相互关联的 PR。每个后续的 PR 都建立在前一个的基础上。

可以这样理解：

1. PR #1：添加数据库 schema（基础：main）。
2. PR #2：实现 API 端点（基础：来自 PR #1 的分支）。
3. PR #3：构建前端界面（基础：来自 PR #2 的分支）。

审查者可以逐个检查。这样更快、更轻松，也更彻底。问题在于 Git 和 GitHub 原生并不擅长处理这种结构。如果你更新了 PR #1，就得手动把改动"向上拉"到所有其他 PR。gh-stack 帮你处理这些繁琐的工作。

实际工作原理

该工具作为官方 GitHub CLI 的扩展安装。如果你已经装了 gh，安装只需要几秒钟：

gh extension install github/gh-stack

创建第一个堆叠

假设你开始处理一个新任务。与其使用常规的 git checkout -b，不如初始化一个堆叠：

gh stack init

然后按常规方式提交代码。当第一个逻辑部分准备好时，不用手动创建分支，只需执行：

gh stack add feature-api

这个命令会在当前分支之上创建一个新分支，并立即切换到该分支。你继续写代码。当堆叠准备好后，一个 gh stack submit 命令就能把所有内容推送到 GitHub。该工具会创建多个 pull request，并正确设置它们的 base branch，使每个 PR 只显示相关的 diff，而不是把所有之前分支的改动混成一团。

导航和修改

gh-stack 最实用的功能之一是导航。忘记分支名了？没问题。

• gh stack up — 在堆叠中向上移动一层。
• gh stack down — 向下回到基础分支。
• gh stack tree — 查看整个结构。

如果审查者要求你修改第一个 PR，你只需向下（gh stack bottom），进行修改，然后运行 gh stack rebase。神奇的是，该工具会自动将改动向上传播到整个堆叠，更新所有中间分支。不再需要手动连续变基五个分支。

通过 TUI 管理

对于喜欢可视化控制的人，可以使用 gh stack modify 命令。它会在终端中打开一个交互式界面。在那里你可以：

• 重新排序分支。
• 将多个分支合并为一个。
• 移除堆叠中不必要的部分。
• 重命名层级。

这比通过 git rebase -i 和无休止的分支切换来做同样的事情要直观得多。

同步和完成工作

当你的 PR 开始合并到 main 分支时，就该用 gh stack sync 了。这个命令同时做几件事：从 main 拉取更改、更新本地堆叠，并建议删除已合并 PR 的分支。

顺便说一句，该工具还可以与 AI 代理配合使用。如果你使用代码生成的自动化，可以安装 gh skill install github/gh-stack 技能，让代理理解你的分支结构，不会破坏堆叠。

有什么注意事项吗？

该项目目前处于公开预览阶段。这意味着某些功能（如 GitHub 界面中直接显示美观的 PR 关系）需要在你的仓库中启用该功能。如果尚未激活，你可以加入等待列表。

然而，即使没有服务端组件，作为管理分支链的本地辅助工具，gh-stack 已经相当可用了。

谁适合使用

如果你在大型团队中工作，有严格的代码审查流程，这个工具会为你节省大量时间。它消除了分支"分层"的恐惧，让你专注于代码而不是 Git 管理。

如果你是项目唯一的开发者，所有内容都直接合并到 main，你可能不需要这个。但对于其他所有人来说，这是一个让 PR 更人性化、更易于审查的好方法。

光是 gh stack alias 命令就值得一试。它会创建一个短别名 gs，之后使用堆叠就变得完全无缝。例如，gs push 而不是冗长的命令结构。来自 GitHub 自身的简单而有效的工具。