SuperAPI AI 工具集

gh-stack

编程与开发

查看项目

更新于 11-03 12:49

技能介绍

用途

gh-stack 用于在 GitHub 上创建和管理“原生堆叠式 PR”(Stacked Pull Requests)。它封装 github/gh-stack 扩展,使本地的一条分支链变成 GitHub 上真实的 Stack:每层一个 PR、链式基底、逐层 diff 视图、关联合并,而不是手工搭建的链式基底 PR 集合。

主要能力

  • 环境检测(只读):检查 gh 版本、认证状态(仅退出码)、扩展列表、PR 列表与详情、Stack 的 REST 端点、git 分支与合并基点,以及扩展的跟踪文件 <git-dir>/gh-stack。
  • 安装扩展:执行 gh extension install github/gh-stack 前,先经 AskUserQuestion 询问用户,绝不静默安装。
  • 解析分支链:支持显式传入的分支链(底部在前)或扩展本地跟踪的栈。
  • 发布 Stack:仅执行扩展的三个子命令——gh stack link、gh stack push、gh stack submit --auto;每次调用都要求逐次用户授权。
  • 验证与报告:执行后逐项读回结果,而不是只信退出码。

使用方式

/gh-stack [--base <trunk>] [<branch>...]      # 显式链,底部在前;仅解析并报告
/gh-stack --link [--base <trunk>] <branch-or-pr>...  # 命名一条链:推送、创建/链接 PR、创建 Stack
/gh-stack --submit                            # 发布扩展已本地跟踪的栈(无参数)
/gh-stack --push                              # 推送已跟踪栈的分支,不改变 PR
/gh-stack --open                              # 与 --link 或 --submit 搭配:将新老 PR 标记为可评审
/gh-stack --install                           # 仅检测并询问是否安装

工作流:阶段 0 检测 → 阶段 1 安装(需授权)→ 阶段 2 解析链 → 阶段 3 授权并执行 → 阶段 4 验证与报告。任何不带 --install 且不带变更标志的运行都是只读的:检测、解析、报告。

授权与推送安全

  • 三个授予的子命令都会推送远端引用与 PR 状态;link 使用普通 git push --atomic(无强制),push 与 submit --auto 使用按分支、带值的 git push --force-with-lease=refs/heads/<b>:<sha>。
  • 未经授予的子命令(view、rebase、sync、modify、merge、unstack、init、add、checkout)只打印给用户,绝不执行:它们会重写本地历史、合并 PR 或需要 TUI。gh stack view 虽像查询,但会同步 PR 元数据并回写 .git/gh-stack,属于变更。
  • gh stack submit 不带 --auto 绝不运行:交互模式会打开全屏编辑器,可能挂起会话。
  • 对 push 与 submit --auto,阶段 3 在强制推送授权前按名称询问“是否有其他人在这些分支上工作”,答案不是未共享声明时拒绝调用。lease 只防 fetch 与 push 之间的竞态,不是共享性检查。
  • 技能绝不设置 ALLOW_PUSH_PROTECTED 与 ALLOW_FORCE_UNSHARED,并在每次执行时清除;ALLOW_FORCE_WITH_LEASE 仅设置在经批准的那一条命令上,且不用于 link。
  • 受保护分支(main/master/develop/release/* 及项目新增)可作为栈基,绝不可作为栈层;阶段 2 发现即硬中止。

版本绑定

推送形式依据 github/gh-stack v0.1.1 源码确定:link 为 git push <remote> --atomic refs/heads/<b>:refs/heads/<b> …,无强制;push 与 submit --auto 为按分支、带 lease 的非原子推送。版本不是 v0.1.1 时推送形式未经核验,所有变更运行在阶段 3 前停止并报告所发现版本。GIT_TRACE 或 GH_DEBUG 不能替代源码核验。

变更面

三个子命令除推送外还有其它状态变更:link 会为没有 PR 的分支创建 PR(默认草稿,除非 --open),重定向已有 PR 的基底,创建或扩展 Stack;push 会写 .git/gh-stack;submit --auto 会先以非交互方式解决待处理 modify(可能解除一个并非正在提交的栈),逐层推送,关闭已有 PR 的 auto-merge、必要时重定向基底、按 --open 标记就绪、创建 PR 文本、创建或扩展 Stack、写跟踪文件。授权须覆盖这些变更;技能拒绝而非批准“解除栈”这类操作。

适用场景

  • 将显式命名的分支链发布为 GitHub Stack。
  • 发布扩展已在本地跟踪的栈。
  • 仅推送已跟踪栈的分支而不改动 PR。

限制

  • 不执行授权之外的扩展子命令。
  • 非 v0.1.1 版本下不执行任何变更操作。
  • 每次变更调用均需用户逐次显式授权;不存在可替代提问的标志或先前授权。
  • --submit 与 --push 不接受分支参数;带分支参数属于参数错误。
  • 未提供关于费用、价格或平台支持范围的信息。