SuperAPI AI 工具集

gh-stack

通用与其它

查看项目

更新于 10-15 23:42

技能介绍

用途:gh stack 是 GitHub CLI 扩展,用于堆叠分支和拉取请求。堆叠是以主干为根的有序分支链,每个分支基于其下一层分支并对应一个 PR,评审者只看到该层差异。堆叠按主干优先从左到右打印,如 (main) <- auth <- api <- frontend,左侧为底部先合并,右侧为顶部后合并;up 向顶部移动,down 向主干移动。

安装与配置:gh extension install github/gh-stack;git config rerere.enabled true;git config remote.pushDefault origin(多远程仓库必需)。

非交互使用:gh stack 根据 stdout 是否为 TTY 决定行为,管道下多数命令报错或输出静态文本,PTY 下会打开提示或全屏 TUI 并阻塞。应始终传标志:gh stack view --json、gh stack submit --auto、gh stack merge <target> --yes、gh stack init <branch>...、gh stack add <branch>、gh stack checkout <target>、gh stack up/down/top/bottom。多远程时,push、submit、sync、rebase、link 必须加 --remote <name>,除非配置了 remote.pushDefault;checkout 和 trunk 无 --remote 标志,依赖该配置。

核心流程:gh stack init auth 创建堆叠并检出分支;提交后 gh stack add api 添加下一层;gh stack submit --auto 推送所有分支并创建草稿 PR(加 --open 创建待评审 PR);gh stack view --json 确认。gh stack sync 同步并刷新 PR 状态,--prune 删除已合并 PR 的本地分支。

合并:仅在用户要求整栈合并时使用 gh stack merge,传 PR 号合并该 PR 及其下方所有未合并 PR,或传堆叠号合并该堆叠全部未合并 PR;操作是全有或全无。无方法标志时复用上次方法;若基分支使用合并队列,则改为排队并忽略标志。

读取状态:gh stack view --json 输出 JSON 到 stdout,状态消息到 stderr,应依据退出码而非解析消息。退出码 0 成功、1 通用错误、2 不在堆叠、3 rebase 冲突、4 GitHub API 失败、5 参数无效、6 需消歧、7 rebase 已在进行、8 堆叠文件锁定、9 堆叠 PR 不可用、10 需 modify 恢复。

限制:堆叠严格线性,一个父分支至多一个子分支,并行工作用独立堆叠;无非交互式重排或删除,modify 仅 TUI;PR 标题和正文自动生成,之后用 gh pr edit 修改;checkout <branch-name> 仅解析本地堆叠。更多细节见 references/stack-design.md、commands.md、troubleshooting.md。