Next.js 仓库中的 gh-stack 命令行为详解从 init 到 merge 的前置条件、副作用与失败模式【免费下载链接】next.jsThe React Framework项目地址: https://gitcode.com/GitHub_Trending/next/next.js在 Next.js 仓库的.agents/skills/目录中gh-stack是一个面向 Agent 与开发者协作的技能skill其参考文件 commands.md 专门记录gh stack各子命令的前置条件、副作用、原子性与失败模式——即--help不解释的那部分行为。读完本文你能掌握gh stack每个命令在什么条件下失败、失败时以什么退出码退出、命令之间哪些操作是原子的哪些不是以及如何把 Next.js 仓库这种多分支协作场景下的分支栈stacked branches / 依赖式 PR 链稳定地驱动起来包括在脚本、CI 和 Agent 会话中安全使用它的规则。1. 技能定位文档明确划定自身的解释边界gh stack是 GitHub CLI 的扩展用于管理堆叠式分支与堆叠式 PR一个栈是一根以 trunk主干分支为根的有序分支链每个分支有一个基于其下方分支的 PR评审者因此只看到本层的 diff。栈的展示方式是 trunk 在左、自左向右向上(main) - auth - api - frontend左侧是底层先合入右侧是顶层最后合入up朝栈顶、远离 trunkdown朝 trunk。基础层如认证、模型放底部依赖它的代码放其上。commands.md 开篇就声明了自己的定位这是使用整套文档的前提gh stack command --helpis authoritative for flags and arguments.gh stack help commandonly prints the top-level help.This file only covers behavior--helpdoes not explain: preconditions, side effects, atomicity, and failure modes.即参数和标志以command --help为权威注意gh stack help command是不起作用的——它只打印顶层帮助这一点在 SKILL.md 的 More detail 一节再次强调。commands.md只补充--help覆盖不到的行为面前置条件、副作用、原子性、失败模式。这也决定了本文的组织方式——逐命令拆解这四类信息。2. 环境准备与非交互使用规则来自技能主文档在进入逐命令语义之前先给出 SKILL.md 中定义的三行安装配置这是所有命令的适用前提gh extension install github/gh-stack git config rerere.enabled true # remember conflict resolutions git config remote.pushDefault origin # required if the repo has more than one remote其中后两条配置与commands.md的内容直接相关rerere.enabledinit命令会启用git rerere见第 4 节预先配置可跳过首次运行在 TTY 下的确认提示。remote.pushDefault当仓库存在多个 remote 时push、submit、sync、rebase、link都必须显式带--remote namecheckout和trunk没有--remote标志只能依赖该配置。Next.js 仓库将gh stack明确按**stdout 是否为 TTY** 来分流行为管道场景下多数命令干净报错或打印静态文本而 PTY 下同样命令会打开提示或全屏 TUI 并永久阻塞。Agent 会话的 harness 各不相同因此技能要求始终显式传标志。SKILL.md 给出的强制规则表如下左列总是这样跑、中列永远不要裸跑、右列原因总是运行不要裸跑原因gh stack view --jsongh stack viewPTY 下会打开 TUIgh stack submit --autogh stack submit每个新 PR 会提示输入标题gh stack merge target --yesgh pr mergegh pr merge无法合并栈gh stack init branch...gh stack init会提示输入分支名gh stack add branchgh stack add提示输入名字且管道下也会失败gh stack checkout targetgh stack checkout打开选择菜单gh stack up/down/top/bottomgh stack switchswitch仅菜单操作—gh stack modify仅 TUI没有非交互路径补充两条边界说明view --short在两种模式下都安全但它是面向人类排版的机器解析请用--json当本地已存在一个覆盖相同分支但构成不同的栈时checkout pr无法强制覆盖——先gh stack unstack --local保留 GitHub 上的栈再重试。一个典型的核心工作流同样来自 SKILL.mdgh stack init auth # create the stack and check out its branch git add ... git commit -m Add auth middleware gh stack add api # next layer, branched from the current one git add ... git commit -m Add API routes gh stack submit --auto # push every branch and open draft PRs gh stack view --json # confirmsubmit加--open可让 PR 直接进入可评审状态而非草稿。分支名按字面使用gh stack add refactor/foo创建的分支名字就是refactor/foo不做任何前缀或转换。3.init自底向上建立整条链并顺手启用rererecommands.md对init的记录要点一次init铺整条链并检出最后一个分支gh stack init auth api frontend会依次创建或接管auth、api、frontend最后停在frontend栈顶上。参数按从底到顶的顺序处理已存在的分支被接管adopt而不是重建第一个分支若不存在则从 trunk 创建其后每个新分支都从它前一个分支创建。没有单独的 adopt 模式——分支是否存在决定行为。--base用于选择非默认的 trunk。init会启用git rerere。在 TTY 下仓库内的首次运行会要求确认提前git config rerere.enabled true可跳过。存在即接管这条设计在重组栈时非常有用troubleshooting.md 的 Restructuring a stack 一节正是利用它——先unstack拆掉本地追踪与 GitHub 分组改写 Git 祖先关系后重新init已有分支会被复用已有 PR 也会保留。4.add只能在栈顶新增退出码 5 是主要失败信号commands.md中add的行为约束是四条每一条都对应一个具体的失败模式必须从栈的顶层分支运行栈还空着时从 trunk 运行。在其他任何分支运行都会以退出码 5退出并打印can only add branches on top of the stack。正确做法是先gh stack top。未提交改动会被带走不带-Am时add不触碰工作区已暂存与未暂存的改动会跟着你进入新分支。想要干净起点就先提交或 stash。add -Am在当前分支还没有任何提交时是就地提交而不是建分支——典型场景就是init之后立刻执行。这是刻意设计栈的第一层通常要先有内容第二层才有意义。-A与-u互斥且两者都要求-m。对照 SKILL.md 的退出码表退出码 5 的语义是 Invalid arguments恢复方式是修正调用方式参见command --help。而 stack-design.md 进一步给出为什么要刻意管理暂存区建议直接用git add/git commit而非add -Am快捷方式以便精确控制哪些改动落在哪个分支——例如先在模型分支暂存并提交模型文件再gh stack add api-routes然后在新分支上暂存 API 文件git add internal/models/user.go internal/models/session.go git commit -m Add user and session models gh stack add api-routes git add internal/api/routes.go internal/api/handlers.go git commit -m Add user API routes每个分支允许多次提交关键是同一分支的每个提交服务同一关注点属于另一关注点的改动必须去另一个分支。5.push与submit两种推送语义原子性完全不同这是commands.md中原子性信息最集中的部分。push一次 multi-ref 推送但不原子一次性以 multi-ref 推送所有活动分支未合并、未入队的每个分支带--force-with-lease。非原子可能出现部分分支已更新、另一分支被拒绝的状态。被拒绝意味着该分支在远端被改动过——修好那个分支后重跑即可重跑是安全的已经落地部分会被跳过。push从不创建或更新 PR需要 PR 语义时用submit。submit推送 建 PR 链接成 Stacksubmit依次完成推送每个活动分支 → 为没有 PR 的分支创建 PR基于其第一个未合并的祖先→ 在 GitHub 上把它们链接成 Stack。四个关键行为非原子。分支按序推送每个分支--force-with-lease若后面某个推送被拒绝前面的推送和 PR 更新保留。修复拒绝后重跑同一条命令。完全合并的栈无法被延长。当当前栈的所有 PR 都已合并时submit会把剩余未合并分支分叉成一个新栈以 trunk 为根在 GitHub 上创建原合并栈保持不动。--auto的标题生成规则单提交分支用该提交的 subject 作标题、body 作 PR 正文多提交分支则把分支名人性化连字符与下划线变空格。没有自定义标题/正文的标志——之后用gh pr edit修改。--open让新 PR和已有 PR 都进入可评审状态不带则新 PR 为草稿。前置条件仓库必须启用 Stacked PRs。未启用时非交互模式下submit以退出码 9退出TTY 下会提供创建普通未堆叠 PR 的替代路径。对照 SKILL.md 的退出码表退出码 9 正是 Stacked PRs unavailable —— 仓库未启用告知用户。6.link无本地追踪状态的建栈路径commands.md将link定位为不写任何本地追踪状态不碰.git/gh-stack文件的建栈/更新栈路径专为分支由其他工具管理、或位于另一个 worktree的场景设计详见 troubleshooting.md 的 Driving stacks from another tool or worktree 一节其中明确提到 jj、Sapling、git-town 等工作流。行为要点参数自底向上。每个参数是分支名或 PR 号数字参数先尝试按 PR 号解析失败再回退为分支名。首参为数字时仅当存在该编号的栈才按栈号处理。此时剩余参数被追加到该栈顶部无需重列栈内现有 PRgh stack link 7 feature-c。已在栈内的参数跳过属于其他栈的参数被拒绝。分支参数会被自动推送非 force、原子缺失的 PR 用自动生成标题、正确链式 base 创建base 错误的已有 PR 会被纠正。栈成员关系只增不减——link从不把 PR 移出栈。注意一个后果因为link不写本地状态基于本地状态的导航命令up、down、top、bottom对其结果无效之后需要本地追踪时用gh stack checkout stack-number。7.sync八步例行动作冲突时全体回滚sync是日常最常用的命令commands.md按顺序记录了它的八步值得完整理解Fetch从远端拉取。与 GitHub 上的栈对账在 github.com 上加入栈的 PR 会被拉取并本地追加发现分歧divergence时非交互模式下中止恢复方案见 troubleshooting.md。快进 trunk已最新则跳过分歧则告警。需要时级联 rebase触发条件是——trunk 前进了、某个栈分支从其远端被快进了、或某分支不再包含其预期父分支。已合并 PR 会被自动处理squash 合并场景用--onto规避伪冲突。发生冲突时所有分支被恢复到 rebase 前状态命令以退出码 3 退出。推送所有活动分支原子地。刷新 PR 状态从 GitHub 拉取最新。同步栈对象把 open PR 增量地链接成栈仅当存在两个及以上 PR 时执行。sync从不打开 PR——那是submit的职责。清理删除已合并 PR 对应的本地分支仅当非交互环境下传入--prune时发生。几个值得强调的边界退出 0 不代表成功同步SKILL.md 特别指出当本地与远端栈分歧时sync会打印两条链、不做任何改动、以退出码 0 加Sync aborted消息结束。脚本必须检查该消息或重跑gh stack view --json比对。退出码 3 的恢复sync失败时栈已被恢复直接gh stack rebase重新触发 rebase然后解冲突--continue详见第 8 节。分歧的两条恢复路径保留远端版unstack --localcheckout stack-number保留本地版unstacksubmit --auto都不删除任何 PR 或分支但远端 unstack 会保留处于 auto-merge 或 merge queue 中的 PR 的堆叠状态必要时先清理该状态。8.rebase级联重放、squash 合并感知、退出码 7 保护rebase从远端拉取并做级联 rebase。commands.md的要点适用时机sync报告冲突后或只需要 rebase 栈的一部分时。--upstack从当前分支向栈顶 rebase——编辑底层之后要跑的就是它。SKILL.md 的标准片段是gh stack down # or: gh stack checkout api git add ... git commit -m Add get-user endpoint gh stack rebase --upstack # replay every branch above onto the change gh stack top # return to where you were gh stack push--downstack从 trunk rebase 到当前分支。--no-trunk跳过 fetch 与 trunk rebase只做栈分支之间的相互对齐。--continue解决完暂存冲突后续跑--abort恢复每一个分支不只是当前分支。squash 合并自动感知已合并 PR 会被自动检测并用--onto针对正确目标重放因此 squash 合并的父分支不会产生伪冲突troubleshooting.md 的 After a squash merge 一节印证sync检测后以--onto重放并跳过已合并分支view --json中该分支报告isMerged: true, state: MERGED无需手工操作。rebase 进行中的再入保护此时启动新的 rebase 以退出码 7退出对照 SKILL.md 退出码表恢复方式为gh stack rebase --continue或--abort。退出码 3 的标准恢复流程rebase与sync都以此退出但状态不同失败的sync已把栈恢复原状失败的rebase则停在半途等待处理gh stack rebase # exit 3 — conflicted paths are listed on stderr git add resolved paths gh stack rebase --continue # repeat if the next branch also conflicts由于init启用了rerere同一冲突解决过一次后会自动重放——这在栈中很常见因为栈底部的改动会被 rebase 穿过其上方的每一个分支没有rerere时重复冲突可能在每一层都要手工解决。9.view与checkout机器可读状态与解析优先级view--json把机器可读负载写到stdout状态消息走stderr——脚本不要解析 stderr应按退出码分支。--json的 schema记录在 SKILL.mdtrunk string currentBranch string branches[] name, head, base, isCurrent, isMerged, isQueued, needsRebase branches[].pr number, url, state (OPEN | MERGED | QUEUED); absent when no PR exists其中base是该分支最后已知包含的父分支的保存 SHA可能比父分支当前 tip 旧当当前父分支 tip 不再是该分支的祖先时needsRebase为真。裸view在 stdout 为 TTY 时打开全屏 TUI管道时打印静态文本。--short打印每分支一行的紧凑摘要、从不打开 TUI但它是人类排版解析请改用--json。view会尽力而为地从 GitHub 刷新 PR 状态作为副作用——API 不可达时不失败。checkout接受栈号、PR 号、PR URL 或分支名解析优先级与副作用如下裸数字的解析顺序先栈号再 PR 号最后分支名。栈号、PR 号、PR URL 都会从 GitHub fetch、拉取分支并在本地建立栈。分支名只对本地已追踪的栈解析从不接触 GitHub要拉取本地未追踪的栈必须用栈号或 PR 号。若本地已存在覆盖这些分支但构成不同的栈checkout无法强制越过——先gh stack unstack --local再重试。checkout没有任何标志多 remote 时依赖remote.pushDefault。10.unstack与merge拆组不删 PR合并全有或全无unstack只移除栈的分组从不删除 PR 或分支无参数时作用于活动栈包含当前分支的那个同时移除 GitHub 分组与本地追踪。带栈号时从仓库任意位置、无论是否本地追踪都通过 API 工作存在本地追踪时一并移除。--local只删本地追踪从不接触 GitHub对一个本地未追踪的栈号组合--local是错误。未知栈号以退出码 2 退出。mergecommands.md中merge是最强调整体性的命令作用域由参数决定传 PR 号 → 合并该 PR 及其下方所有未合并 PR传栈号 → 合并该栈内所有未合并 PR。全有或全无all-or-nothing该合并集合中任何一个 PR 无法合并则一个都不合并并报告原因。合并方式来自--squash、--rebase、--merge或--merge-method method都不传则复用上次使用的方法。合并前只检查基础 PR 状态open 且非草稿。栈不支持绕过合并要求merge requirements。base 分支上的 merge queue 压倒一切栈会被加入队列而非直接合并队列选择合并方式你传入的方式标志会被忽略并告警。入队 PR 是一起提交的但随队列处理可能分组落地而非一次性全部合入。gh pr merge无法合并栈必须始终用gh stack mergeSKILL.md 的非交互表亦强制裸gh stack merge会提示确认脚本中应写gh stack merge target --yes。示例gh stack merge 42 --yes # PR #42 plus every unmerged PR below it gh stack merge 7 --yes # every unmerged PR in stack #7 gh stack merge 42 --yes --squash # or --merge, --rebase, --merge-method method11. 导航命令永远非交互边界钳制与合并分支跳过commands.md的 Navigation 一节很短但信息密度高up、down、top、bottom、trunk永远是非交互的up/down接受步长gh stack up 3。移动在栈边界处钳制clamp从活动分支导航时跳过已合并分支因此bottom落在最低的未合并分支上。gh stack switch是纯选择菜单没有非交互路径——脚本中应使用上述命令替代SKILL.md 的非交互表也把switch列入永远不要裸跑。12. 退出码全景Agent 与脚本如何分支处理commands.md在命令叙述中散落出现的退出码2、3、5、7、9与 SKILL.md 中完整的退出码表拼在一起构成完整的机器可判定语义退出码含义恢复方式0成功—1通用错误读 stderr2不在栈中含unstack遇到未知栈号gh stack init或gh stack checkout target3rebase 冲突解冲突后rebase --continuesync场景栈已恢复重跑rebase4GitHub API 失败检查gh auth status重试5参数错误含非栈顶执行add修正调用参见command --help6需要消歧分支同属多个栈检出该栈内不共享的分支后重试7rebase 已在进行gh stack rebase --continue或--abort8栈文件被锁另一gh stack进程在写入约 5 秒后重试9仓库未启用 Stacked PRs告知用户非交互下submit以此退出10需要 modify 恢复gh stack modify --abort两条与锁和 TUI 相关的补充事实来自 troubleshooting.md退出码 8 对应另一进程持有.git/gh-stack.lock的排他锁锁约 5 秒超时持续出现 8 说明仍有进程持锁先定位并结束该进程退出码 10 对应被中断的modify会话modify是 TUI-onlyAgent 不应调用恢复方式为gh stack modify --abort且submit也会检测 pending modify 状态并在 TTY 下询问是否用本地状态覆盖 GitHub 上的栈。退出码 6 的典型场景是当前分支同时是多个栈的 trunk没有任何标志可以消歧gh stack checkout a-branch-unique-to-the-intended-stack后重试而接受显式栈号的命令merge 7、unstack 7因为不从当前分支推断栈天然绕开该问题。13. 三个参考文件的分工按需加载而非预载gh-stack技能目录是 Next.js 仓库技能体系 中hub 细节文件模式的实例SKILL.md 是入口setup、非交互规则、核心循环、退出码、JSON schema、约束三个 references 各自对应一类触发条件stack-design.md —— 建栈之前读定层数、定每层内容、判断工作是否该进新栈。核心观点包括栈是依赖链依赖必须与代码同分支或在更底层且规划期满足远比事后重组便宜因为没有非交互的原地重排改顺序意味着unstackinit分支命名推荐topic/concern如billing/schema、billing/api但用户与仓库的分支命名规范优先一个栈讲一个故事——同一功能用单栈无关工作开新栈。commands.md ——本文主体命令失败得意外、或需要其前置条件/副作用/原子性/顺序保证时读。troubleshooting.md —— 出 rebase 冲突、squash 合并之后、本地远端分歧、重组栈、或其他工具驱动栈时读。SKILL.md 明确Open the reference whose trigger matches the task; no need to preload all three.打开触发条件匹配的那份参考即可无需三份全读。这个技能也在 create-pr 技能 中被交叉引用为管理堆叠分支与依赖式 PR的入口说明它是 Next.js 仓库 PR 工作流技能图谱中的一环。14. 关键约束速查汇总 SKILL.md 的 Constraints 与commands.md的行为事实以下是日常协作中最容易踩中的硬约束栈是严格线性的一个父、至多一个子并行工作用独立栈。没有非交互的重排或移除报错信息可能提示gh stack modify但它只有 TUI——重组请用unstack然后init重建init会接管已存在分支PR 不丢失Git 祖先关系正确后submit会更新 base 并重新链接栈。改元数据不等于改祖先关系想调层顺序先按 troubleshooting.md 的三步git rebase --onto序列重写祖先再重建栈移动分支前先保存旧的边界 SHA。PR 标题与正文自动生成之后用gh pr edit修改。checkout branch-name只解析本地栈从 GitHub 拉栈必须用栈号或 PR 号。15. 小结commands.md 的价值在于把gh stack从看起来是普通 git 封装提升为行为可预测的工具push/submit非原子但可安全重跑sync冲突时全体回滚并以退出码 3 报告rebase有退出码 7 的再入保护merge全有或全无且受 merge queue 覆盖link/unstack --local提供不碰 GitHub 或纯 API 的对称路径checkout的解析优先级决定了何时接触 GitHub。把这些与 SKILL.md 的退出码表和 troubleshooting.md 的恢复剧本合起来Agent 与 CI 脚本都能在 Next.js 仓库这类大团队协作场景中可靠地把多分支工作拆成可评审的 PR 层并在任何失败状态下按退出码走确定的恢复路径。【免费下载链接】next.jsThe React Framework项目地址: https://gitcode.com/GitHub_Trending/next/next.js创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考