stack

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Stack

Use the local

stack

CLI for squash-safe stacked PR repair. It is designed for repos where PRs are squash-merged and merged branches are deleted, so Git ancestry alone cannot preserve stack intent.

Keep ordinary editing and commits on plain

git

. Use

stack

only for stack intent, stack inspection, sync, merge, and undo workflows.

使用本地

stack

CLI 进行 squash-safe 的堆叠PR修复。它专为采用 squash-merge 方式合并PR、且合并后分支会被删除的仓库设计，因此仅靠Git祖先记录无法保留堆叠意图。

日常编辑和提交使用普通的

git

即可。仅在处理堆叠意图、堆叠检查、同步、合并和撤销工作流时使用

stack

。

Mental Model

心智模型

text

dev
└─ stack-a  #101
   └─ stack-b  #102
      └─ stack-c  #103

Stack intent is persisted in

.git/stack/state.json

as stack links:

branch
parent branch
merge-base anchor
PR number

Mutating sync and merge workflows write

.git/stack/undo.json

stack undo --apply

can restore the previous branch tips, PR bases, and stack metadata.

text

dev
└─ stack-a  #101
   └─ stack-b  #102
      └─ stack-c  #103

堆叠意图以堆叠链接的形式保存在

.git/stack/state.json

文件中，包含以下信息：

分支
父分支
合并基准锚点
PR编号

修改类的同步和合并工作流会写入

.git/stack/undo.json

，因此可通过

stack undo --apply

恢复之前的分支尖端、PR基准和堆叠元数据。

Common Commands

常用命令

```
stack status
```
: show the relevant tracked stack graph and include open PR details when GitHub is available.
```
stack guide
```
: print the opinionated happy path for agents and humans.
```
stack track <branch> --onto <parent>
```
: record stack intent for an existing branch.
```
stack sync --dry-run [branch]
```
: preview inferred PR-base stack links and repairs without changing branches or PRs.
```
stack sync [branch]
```
: infer clear PR-base stack links, repair descendants, retarget PRs, and refresh stack blocks. With a branch argument, sync only the stack containing that branch.
```
stack sync --continue-on-failure
```
/
```
stack sync --keep-going
```
: process independent stacks, summarize successes and failures, and exit nonzero if any stack failed.
```
stack doctor
```
: inspect local Git, GitHub, stack metadata, trunk branches, and undo journal health without changing anything.
```
stack merge [branch]
```
: dry-run root PR merge plus descendant repair.
```
stack merge [branch] --apply
```
: retarget immediate child PRs, squash-merge the root PR, then repair descendants.
```
stack merge [branch] --auto
```
: retarget immediate child PRs, enable GitHub auto-merge, wait, then repair descendants.
```
stack merge --auto --through <branch-or-pr>
```
: repeat auto-merge one root at a time until the target branch or PR lands.
```
stack history
```
: show the most recent applied repair journal.
```
stack undo
```
: dry-run restore of the most recent applied repair.
```
stack undo --apply
```
: restore branches, PR bases, and stack metadata from the journal.

```
stack status
```
：显示相关的已跟踪堆叠图，当可连接GitHub时，会包含未关闭PR的详细信息。
```
stack guide
```
：打印面向Agent和人类的标准化操作路径。
```
stack track <branch> --onto <parent>
```
：为现有分支记录堆叠意图。
```
stack sync --dry-run [branch]
```
：预览推断出的PR基准堆叠链接和修复操作，不会修改分支或PR。
```
stack sync [branch]
```
：推断明确的PR基准堆叠链接，修复子分支，重新定位PR，并刷新堆叠块。若指定分支参数，则仅同步包含该分支的堆叠。
```
stack sync --continue-on-failure
```
/
```
stack sync --keep-going
```
：处理独立堆叠，汇总成功和失败情况，若有堆叠处理失败则返回非零退出码。
```
stack doctor
```
：检查本地Git、GitHub、堆叠元数据、主干分支和撤销日志的健康状态，不会进行任何修改。
```
stack merge [branch]
```
：预演根PR合并及子分支修复操作。
```
stack merge [branch] --apply
```
：重新定位直接子PR，squash-merge根PR，然后修复子分支。
```
stack merge [branch] --auto
```
：重新定位直接子PR，启用GitHub自动合并，等待合并完成后自动修复子分支。
```
stack merge --auto --through <branch-or-pr>
```
：逐个自动合并根PR，直到目标分支或PR合并完成。
```
stack history
```
：显示最近应用的修复日志。
```
stack undo
```
：预演恢复最近一次应用的修复操作。
```
stack undo --apply
```
：从日志中恢复分支、PR基准和堆叠元数据。

Happy Path: PR Bases Encode The Stack

理想工作流：PR基准定义堆叠

bash

gh pr create --base dev --head stack-a
gh pr create --base stack-a --head stack-b
stack sync --dry-run
stack sync
stack sync cleanup/schema-source
stack sync --keep-going

Prefer this workflow.

stack sync --dry-run

should show the inferred links, and

stack sync

records them, removes stale local links, repairs descendants if needed, retargets PRs, and refreshes stack blocks.

Use

stack guide

when you need the CLI itself to print this guidance.

bash

gh pr create --base dev --head stack-a
gh pr create --base stack-a --head stack-b
stack sync --dry-run
stack sync
stack sync cleanup/schema-source
stack sync --keep-going

优先采用此工作流。

stack sync --dry-run

应显示推断出的链接，

stack sync

会记录这些链接、移除过时的本地链接、必要时修复子分支、重新定位PR，并刷新堆叠块。

当需要CLI自行打印此操作指南时，使用

stack guide

。

Inspect A Stack

检查堆叠

bash

stack status

Use this to understand local stack metadata, current branch position, missing parents, tracked PR numbers, and PR titles when GitHub is available. It is opinionated: backup branches are hidden, and when the current branch is stack-relevant it focuses on that stack instead of listing every local branch.

Use

stack sync --dry-run

, not

stack status

, when you need GitHub PR-base inference before mutation.

bash

stack status

使用此命令了解本地堆叠元数据、当前分支位置、缺失的父分支、已跟踪的PR编号，以及当可连接GitHub时的PR标题。该命令具有倾向性：会隐藏备份分支，且当当前分支与堆叠相关时，会聚焦于该堆叠而非列出所有本地分支。

当需要在修改前通过GitHub PR基准进行推断时，请使用

stack sync --dry-run

，而非

stack status

。

Track Existing Branches

跟踪现有分支

bash

stack track stack-b --onto stack-a
stack track stack-c --onto stack-b

This records stack intent without changing commits or PRs. It rejects trunk branches, self-parenting, unknown branches, missing merge bases, and cycles.

bash

stack track stack-b --onto stack-a
stack track stack-c --onto stack-b

此命令会记录堆叠意图，但不会修改提交或PR。它会拒绝主干分支、自关联父分支、未知分支、缺失合并基准的分支以及循环分支。

Sync The Common Safe Workflow

同步通用安全工作流

bash

stack sync --dry-run
stack sync

Use

sync

when open PR bases already describe the stack, a parent PR branch has changed, or the repo needs the safe common maintenance flow. It:

infers clear PR-base stack links
removes stale local stack links when no open PR depends on them
updates stale explicit links when open PR bases clearly show the current stack
skips standalone trunk-root PRs unless another open PR is based on them
repairs descendants after squash merges or parent drift
retargets PR bases
refreshes stack blocks in PR bodies
prints a concise tree summary of changed, planned, or failed branches

Run

stack sync --dry-run

first when you want a preview of inferred links and repairs before mutation.

stack sync <branch>

scopes sync to the stack containing that branch. If no branch is provided and the current branch is stack-relevant, bare

stack sync

scopes to the current stack; if the current branch is off-stack, it keeps the repo-wide behavior.

--dry-run

follows the same scoping rules.

Use

stack sync --continue-on-failure

stack sync --keep-going

when one independent stack should not block the rest. It runs each root stack separately, prints succeeded and failed stacks, preserves the usual failure cleanup block for each failed stack, saves undo information for every mutated stack, and exits nonzero if any stack failed.

Sync output is intentionally outcome-oriented. It should show the stack tree with icons like

●

✓

◌

, and

✕

, plus changed PRs/backups/undo instructions. It should not default to internal phase logs like fetch, inspect, or reconcile.

If a replay fails,

stack sync

aborts the failed cherry-pick, restores the original branch, deletes the temporary replay branch, keeps backups and the undo journal, and tells the user which branch to repair before running

stack sync

again.

Do not edit

.git/stack/state.json

by hand. If local metadata is stale, run

stack sync --dry-run

; if the preview is correct, run

stack sync

bash

stack sync --dry-run
stack sync

当未关闭PR的基准已描述堆叠、父PR分支已更改，或仓库需要安全的通用维护流程时，使用

sync

命令。它会：

推断明确的PR基准堆叠链接
当没有未关闭PR依赖过时的本地堆叠链接时，将其移除
当未关闭PR基准明确显示当前堆叠时，更新过时的显式链接
跳过独立的主干根PR，除非有其他未关闭PR基于它
在squash合并或父分支偏移后修复子分支
重新定位PR基准
刷新PR正文中的堆叠块
打印简洁的树状摘要，展示已更改、计划更改或处理失败的分支

当需要在修改前预览推断出的链接和修复操作时，请先运行

stack sync --dry-run

。

stack sync <branch>

将同步范围限定为包含该分支的堆叠。若未提供分支参数且当前分支与堆叠相关，则不带参数的

stack sync

会限定在当前堆叠；若当前分支不属于堆叠，则保持仓库级别的行为。

--dry-run

遵循相同的范围规则。

当一个独立堆叠不应阻塞其他堆叠时，使用

stack sync --continue-on-failure

或

stack sync --keep-going

。它会分别运行每个根堆叠，打印成功和失败的堆叠，为每个失败的堆叠保留常规的失败清理块，为每个已修改的堆叠保存撤销信息，若有堆叠处理失败则返回非零退出码。

同步输出特意以结果为导向。它应显示带有

●

、

✓

、

◌

和

✕

等图标的堆叠树，以及已更改的PR/备份/撤销说明。默认情况下不应显示内部阶段日志，如拉取、检查或协调。

若重放失败，

stack sync

会中止失败的樱桃拣选（cherry-pick），恢复原始分支，删除临时重放分支，保留备份和撤销日志，并告知用户在再次运行

stack sync

前需要修复哪个分支。

请勿手动编辑

.git/stack/state.json

。若本地元数据过时，请运行

stack sync --dry-run

；若预览内容正确，再运行

stack sync

。

Merge The Stack Root

合并堆叠根PR

bash

stack merge
stack merge --apply
stack merge --auto
stack merge --auto --through stack-c

Prefer omitting the branch.

stack merge

infers the root from the current stack branch. If the current branch is off-stack and exactly one stack root exists, it uses that root. If multiple roots exist, it asks for

stack merge <branch>

Use bare

stack merge

as a dry-run. Add

--apply

only when the plan is correct. Before merging, the command retargets immediate child PRs away from the root branch so GitHub repo auto-delete settings are less likely to close descendants. Use

--auto

to retarget immediate child PRs, enable GitHub auto-merge, wait until it lands, then repair descendants automatically. Use

--auto --through <branch-or-pr>

to repeat that root merge flow through a bounded target instead of merging the whole stack by default.

Mutating merge workflows stream progress while they run. Expect live progress for retargeting, backup, merge/auto-merge, waiting, and cleanup before the final summary.

bash

stack merge
stack merge --apply
stack merge --auto
stack merge --auto --through stack-c

优先省略分支参数。

stack merge

会从当前堆叠分支推断根PR。若当前分支不属于堆叠且恰好存在一个堆叠根，则使用该根；若存在多个根，则会提示使用

stack merge <branch>

。

使用不带参数的

stack merge

作为预演。仅当计划正确时才添加

--apply

参数。合并前，该命令会将直接子PR重新定位为不依赖根分支，这样GitHub仓库的自动删除设置就不太可能关闭子PR。使用

--auto

参数可重新定位直接子PR、启用GitHub自动合并、等待合并完成后自动修复子分支。使用

--auto --through <branch-or-pr>

可重复根PR合并流程，直到完成指定目标分支或PR的合并，而非默认合并整个堆叠。

修改类的合并工作流会在运行时流式显示进度。在最终摘要前，应显示重新定位、备份、合并/自动合并、等待和清理的实时进度。

Understand Or Undo The Last Mutation

查看或撤销最近的修改

bash

stack history
stack undo
stack undo --apply

Use

history

to inspect the saved undo journal. Use

undo

first as a dry-run, then

undo --apply

to restore branch tips, PR bases, and stack metadata.

bash

stack history
stack undo
stack undo --apply

使用

history

查看已保存的撤销日志。先使用

undo

进行预演，再使用

undo --apply

恢复分支尖端、PR基准和堆叠元数据。

PR Body Stack Blocks

PR正文中的堆叠块

stack sync

and

stack merge --apply/--auto

refresh a deterministic stack block in open PR bodies:

<!-- stack:links:start -->

stack sync

和

stack merge --apply/--auto

会刷新未关闭PR正文中的确定性堆叠块：

<!-- stack:links:start -->

Stack

#101
#102
#103 👈 current


Checked entries are landed history preserved from the previous block. Open PRs
stay unchecked until they are actually merged. The current PR is bold and marked
with `👈 current`. GitHub renders `#123` as a pull request link, so branch paths
are intentionally omitted from stack blocks.

#101
#102
#103 👈 current


已勾选的条目是从之前的块中保留的已合并历史。未关闭的PR会保持未勾选状态，直到实际合并。当前PR会加粗并标记 `👈 current`。GitHub会将 `#123` 渲染为拉取请求链接，因此堆叠块中特意省略了分支路径。

Safety Rules

安全规则

```
stack merge
```
is dry-run by default.
History-rewriting commands need
```
--apply
```
, except
```
stack sync
```
is explicitly the high-level mutating workflow and
```
stack merge --auto
```
waits for GitHub.
Never mutate trunk branches such as
```
dev
```
,
```
main
```
, or
```
master
```
.
Before rebasing a branch, the tool creates a local backup branch.
If output is unclear, inspect with
```
stack status
```
,
```
stack history
```
, or command help before applying.

```
stack merge
```
默认是预演模式。
重写历史的命令需要添加
```
--apply
```
参数，除了
```
stack sync
```
是明确的高级修改工作流，以及
```
stack merge --auto
```
会等待GitHub操作。
切勿修改主干分支，如
```
dev
```
、
```
main
```
或
```
master
```
。
在重新定基分支前，工具会创建本地备份分支。
若输出不明确，请先使用
```
stack status
```
、
```
stack history
```
或命令帮助进行检查，再执行修改操作。

Do Not Use

请勿使用

Do not recommend GitHub's first-party

gh stack

command for this repair workflow unless the user explicitly asks about

gh stack

itself. This skill is for the local

stack

CLI.

除非用户明确询问

gh stack

本身，否则不要推荐GitHub官方的

gh stack

命令用于此修复工作流。本指南针对的是本地

stack

CLI。