gh-stackx

gh-stackx

使用 gh-stackx gh 扩展，在没有私有预览版 GitHub Stacked PRs API 的仓库中管理堆叠式拉取请求。

适用场景

• 你想创建一系列相互依赖的 PR。
• gh stack submit 失败，并提示 ⚠ Stacked PRs are not enabled for this repository。
• 你需要在堆叠中的分支经过变基或合并后，保持 PR 基础分支正确。
• 你想从堆叠顶部开始合并，而不手动编辑 PR 基础分支。

安全须知

gh-stackx 是 github/gh-stack gh CLI 扩展的便捷封装。它会使用用户配置的 gh 身份验证在本地运行。此技能不会收集、存储或转发 GitHub 凭据，也不会自动安装扩展或其他技能。安装任何 gh 扩展前，请务必先查看其源代码。

先决条件

• 已安装并完成身份验证的 gh CLI。
• 已安装 github/gh-stack 扩展，用于本地堆叠操作。
• 已安装 gh-stackx 扩展。

不要自动运行 gh extension install。安装必须由用户明确发起；授予 gh 凭据前，应先查看源仓库（github/gh-stack 和 ThePlenkov/gh-stackx）。安装步骤请参阅仓库 README。

核心概念

• 主干 — 基础分支，通常为 main。
• 堆叠 — 按顺序排列的一组分支，每个分支都基于前一个分支构建。
• 底部 — 最接近主干的分支。
• 顶部 — 距离主干最远的分支。
• 基础分支 — PR 的父分支。最底层使用主干；其他每一层都使用前一个分支。

工作流

创建堆叠

git checkout main
git pull origin main

gh stackx init feature/auth
# work and commit

gh stackx add feature/api
# work and commit

gh stackx add feature/ui
# work and commit

提交 PR

gh stackx submit       # drafts
gh stackx submit --open

submit 会推送所有分支，并从底部向上创建或更新 PR，同时设置正确的 --base 和 --head。每个 PR 正文都包含一个 ## Stack GFM 表格，展示从顶部到主干的完整堆叠。

主干或父 PR 变更后同步

gh stackx sync
gh stackx sync --remote upstream

sync 会运行 gh stack sync，然后使用 gh pr edit --base 更新所有开放 PR 的基础分支。

从顶部向下合并

gh stackx merge
gh stackx merge --squash
gh stackx merge --rebase

merge 会从堆叠顶部开始，使用 gh pr merge 合并每个开放 PR。

本地导航

以下命令会转交给 github/gh-stack：

gh stackx view --json
gh stackx up
gh stackx down
gh stackx top
gh stackx bottom
gh stackx trunk

gh-stackx 会根据 manifest.yml 报告自身的仓库和版本：

gh stackx --version
gh stackx version
gh stackx -v

重要规则

• 在运行 sync 或 merge 前，保持工作树干净；存在未提交更改时，变基操作会失败。
• 从底部向上创建 PR，确保在打开子 PR 前，其基础分支已经存在。
• 从顶部向下合并，确保依赖的 PR 在其父分支移动前完成合并。
• 不要提交 .git/gh-stack。它是本地元数据。

故障排除

• gh stackx view 失败：确认已安装 github/gh-stack。
• PR 的基础分支不正确：运行 gh stackx sync。
• submit 或 merge 因错误而停止：修复底层的 gh pr 问题，然后重新运行。

延伸阅读

以上已包含完整工作流。更多内容请参阅仓库文档：

• 使用指南 — 包含示例的实用操作指南。
• 堆叠式 PR 方法论 — 介绍堆叠式 PR 的工作原理及其用途。
• 规范 — 完整的命令和架构规范。
• REVIEW.md — 本仓库的审查政策。
• AGENTS.md — 如何参与本仓库的开发。