技能包

gh-stack:用 GitHub CLI 管理叠放 PR

适合在已有 GitHub CLI v2.0+ 时管理叠放分支和 Pull Request,前提是先安装 gh-stack 扩展,并确认后再执行会建分支的 gh stack init。

官方来源 · gh-stack

安装

gh extension install github/gh-stack

适合谁

gh-stack 是一个 GitHub CLI 扩展,用来管理叠放的分支和 Pull Request。适合已经在用 GitHub CLI、并且需要把一组有顺序的分支当成一条 stack 来推进的人。摘要还写明安装扩展需要 GitHub CLI v2.0+。

资料提到可以安装 gh-stack skill,让 AI 编码代理了解叠放 PR 以及 gh stack 命令行;但摘录只写到「安装该 skill」,没有给出第二条安装命令,因此不要自行补一条未出现的安装器。资料没有给出代理产品名单,不要把它理解成某一家编辑器的独占功能。官方说明页是

https://github.com/github/gh-stack

3 分钟完成第一次尝试

官方安装命令就是摘录里的这一条:

gh extension install github/gh-stack

前置:本机已有 GitHub CLI,且版本满足摘要所说的 v2.0+。这条命令会向本机写入扩展,属于有副作用的步骤。先确认当前仓库和账号就是你要用来试 stack 的环境,再执行安装。

安装后的低风险核对:不要立刻建分支。先确认命令 gh stack 已经能被 CLI 找到。资料把 gh stack init 解释为「开始一条新 stack,并创建并签出第一个分支」,这会改工作区,必须先得到确认再运行:

gh stack init

成功信号:安装完成后,gh 能识别 stack 子命令;若你确认要开始新 stack,init 之后当前仓库出现新的第一条分支,并且稍后能在未提交的 .git/gh-stack 里看到 JSON 元数据。若只是想先看说明,停在安装成功即可,不要 init。

使用案例

案例一:开始一条新的叠放分支。在已安装扩展的仓库里,确认可以改分支后执行 gh stack init。资料把这写成创建并签出第一个分支。摘要还提到随后可以加层、推送、查看,再提交一组 PR,但摘录没有给出这些后续子命令的完整写法,因此本案例的完成标准只到「第一条分支已创建并签出」,不要把推送或开 PR 写成已经可复制的步骤。

案例二:核对 stack 元数据落在哪里,用来理解中断 rebase 后该看什么。资料写明:stack 元数据存在 .git/gh-stack,是一份不会提交进仓库的 JSON,用来记录哪些分支属于哪条 stack 以及顺序;中断 rebase 的状态另存在 .git/gh-stack-rebase-state。这是只读检查:打开这两个路径,确认文件是否存在以及 JSON 是否在跟踪当前分支顺序。不要手改这些文件,除非同一页另有步骤;摘录没有给出编辑格式。

使用边界

扩展只覆盖叠放分支与 Pull Request 的管理。元数据在 .git/gh-stack,不进版本库;rebase 中断状态在 .git/gh-stack-rebase-state。init 会创建并签出分支,不是只读命令。

不要编造未出现在摘录里的 skill 安装命令,也不要把摘要里的加层、推送、查看、提交理解成已经给出的子命令清单。资料没有写客户端名单,也没有写如何在非 GitHub CLI 环境使用。超出这些已写明的安装、init 与元数据位置,这份说明覆盖不到。