gh-stack · diff
v0.0.9 to v0.0.9
34 added, 34 removed. Audit A to A.
---
name: gh-stack
- description: Manage stacked branches and pull requests with the gh-stack GitHub CLI extension. Use when creating, pushing, rebasing, syncing, navigating, viewing, restructuring, or merging dependent PR chains and stacked diffs.
- compatibility: Requires git, authenticated GitHub CLI, network access, and the github/gh-stack extension.
+ description: 使用 gh-stack GitHub CLI 扩展管理堆叠分支和拉取请求。适用于创建、推送、变基、同步、切换、查看、重组或合并相互依赖的 PR 链及堆叠差异。
+ compatibility: 需要 git、已认证的 GitHub CLI、网络访问和 github/gh-stack 扩展。
metadata:
author: github
version: "0.0.9"
---
- # Manage stacked pull requests
+ # 管理堆叠拉取请求
- Use `gh stack` for a linear chain of branches where each branch has one focused PR based on the branch below it.
+ 使用 `gh stack` 管理线性分支链，每个分支对应一个聚焦的 PR，并以下一层分支为基准。
```text
main -> data-models -> api -> frontend
```
- Put foundational changes lower in the stack and dependent consumers higher. Use separate stacks for unrelated work.
+ 基础改动放在栈的下层，依赖它的使用方放在上层。无关工作使用独立的栈。
- ## Preflight
+ ## 前置检查
```bash
git rev-parse --git-dir
git status --short
gh --version
gh auth status
gh extension list | rg 'github/gh-stack'
```
- Install when explicitly authorized:
+ 获得明确授权后安装：
```bash
gh extension install github/gh-stack
```
- With multiple remotes, configure the intended default or pass `--remote` where supported:
+ 存在多个远端时，配置目标默认远端，或在支持的命令中传入 `--remote`：
```bash
git config remote.pushDefault origin
```
- ## Non-interactive rules
+ ## 非交互规则
- - Always pass branch names to `init`, `add`, and branch-based `checkout`; omitted arguments can prompt.
- - Always use `gh stack submit --auto`; add `--open` only for ready-for-review PRs.
- - Always use `gh stack view --json`; the default view is interactive.
- - Use normal `git add` and `git commit` to keep each layer deliberate.
- - Before changing a lower layer, navigate down, commit there, then run `gh stack rebase --upstack`.
- - A branch shared by multiple stacks requires checking out an unambiguous branch first.
- - Before `checkout <pr-number>`, remove conflicting local tracking with `gh stack unstack --local` when necessary.
- - Merge with `gh stack merge --yes`; do not substitute `gh pr merge` for stacked PRs.
+ - 调用 `init`、`add` 和基于分支的 `checkout` 时始终传入分支名；省略参数可能触发交互提示。
+ - 始终使用 `gh stack submit --auto`；只有已准备好评审的 PR 才添加 `--open`。
+ - 始终使用 `gh stack view --json`；默认查看模式是交互式的。
+ - 使用常规 `git add` 和 `git commit`，明确控制每一层的改动。
+ - 修改较低层前先切换过去并在该层提交，然后运行 `gh stack rebase --upstack`。
+ - 分支由多个栈共享时，需要先检出一个无歧义的分支。
+ - 执行 `checkout <pr-number>` 前，必要时用 `gh stack unstack --local` 移除冲突的本地跟踪信息。
+ - 使用 `gh stack merge --yes` 合并；不要用 `gh pr merge` 替代堆叠 PR 的合并操作。
- ## Common workflows
+ ## 常用流程
- Create and submit a stack:
+ 创建并提交一个栈：
```bash
gh stack init data-models
- # edit, git add, git commit
+ # 编辑，然后执行 git add 和 git commit
gh stack add api
- # edit, git add, git commit
+ # 编辑，然后执行 git add 和 git commit
gh stack add frontend
- # edit, git add, git commit
+ # 编辑，然后执行 git add 和 git commit
gh stack submit --auto
gh stack view --json
```
- Change a lower layer and update dependents:
+ 修改较低层并更新依赖层：
```bash
gh stack checkout api
- # edit, git add, git commit
+ # 编辑，然后执行 git add 和 git commit
gh stack rebase --upstack
gh stack push
gh stack view --json
```
- Routine synchronization:
+ 日常同步：
```bash
gh stack sync
gh stack view --json
```
- For exact flags, stack linking, restructuring, conflict recovery, merge queues, exit codes, and command-specific behavior, read [the complete command reference](references/complete-reference.md) before executing the relevant operation.
+ 执行相关操作前，阅读 [完整命令参考](references/complete-reference.md)，确认准确参数、栈链接、结构调整、冲突恢复、合并队列、退出码和各命令的具体行为。
- ## Recovery boundaries
+ ## 恢复边界
- - Rebase conflict: resolve reported files, stage them, then `gh stack rebase --continue`; abort with `gh stack rebase --abort` if resolution is unsafe.
- - Multiple-stack ambiguity: check out a specific non-shared branch; do not guess.
- - GitHub API failure: inspect authentication and stderr before retrying.
- - Locked stack state: confirm no active `gh stack` process before retrying.
- - Repository lacks stacked-PR support: report the limitation; do not emulate it with unrelated commands.
+ - 变基冲突：解决报告的文件并暂存，然后执行 `gh stack rebase --continue`；无法安全解决时用 `gh stack rebase --abort` 中止。
+ - 多栈歧义：检出一个明确且不共享的分支，不要猜测。
+ - GitHub API 失败：重试前检查认证和标准错误输出。
+ - 栈状态被锁定：重试前确认没有正在运行的 `gh stack` 进程。
+ - 仓库不支持堆叠 PR：报告限制，不要用无关命令模拟。
- ## Verification
+ ## 验证
- After every mutating workflow, run `gh stack view --json` and verify branch order, bases, PR state, and rebase status. Report commands and actual output coverage rather than claiming the whole stack is healthy from a successful push alone.
+ 每次执行会修改状态的流程后，运行 `gh stack view --json`，验证分支顺序、基准分支、PR 状态和变基状态。报告实际命令及输出覆盖的范围，不要仅凭推送成功就宣称整个栈状态正常。