graphite-stacks

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Graphite Stacks

Graphite 堆叠分支

Trunk-based development with stacked PRs using Graphite CLI.

<when_to_use>

Creating or managing branch stacks
Submitting stacked PRs
Reorganizing branch relationships
Addressing PR feedback across a stack
Recovering from stack corruption
Any
```
gt
```
command usage

</when_to_use>

使用Graphite CLI进行基于主干的开发与堆叠PR管理。

<when_to_use>

创建或管理堆叠分支
提交堆叠PR
重组分支关联关系
处理堆叠分支中的PR反馈
从堆叠损坏中恢复
任何
```
gt
```
命令的使用场景

</when_to_use>

Core Principle

核心原则

Use
gt
commands exclusively. Mixing

git

and

gt

causes sync issues and divergent stacks. The only exception:

git add

for staging (or use

-a

flags).

仅使用
gt
命令。混合使用

git

和

gt

会导致同步问题和堆叠分支不一致。唯一例外：可以使用

git add

暂存变更（或使用

-a

参数）。

This, Not That

正确操作 vs 错误操作

Task	This	Not That
Create branch	`gt create 'name' -am "msg"`	`git checkout -b name`
Commit changes	`gt modify -acm "msg"`	`git commit -m "msg"`
Push to remote	`gt submit`	`git push`
Rebase stack	`gt restack`	`git rebase`
View stack	`gt status` or `gt ls`	`git log --graph`
Switch branches	`gt checkout`	`git checkout`
Amend commit	`gt modify -a`	`git commit --amend`
Multi-PR feedback	`gt top && gt absorb -a`	Cherry-pick commits manually

任务	正确操作	错误操作
创建分支	`gt create 'name' -am "msg"`	`git checkout -b name`
提交变更	`gt modify -acm "msg"`	`git commit -m "msg"`
推送到远程	`gt submit`	`git push`
变基堆叠分支	`gt restack`	`git rebase`
查看堆叠分支	`gt status` 或 `gt ls`	`git log --graph`
切换分支	`gt checkout`	`git checkout`
修改提交	`gt modify -a`	`git commit --amend`
多PR反馈处理	`gt top && gt absorb -a`	手动拣选提交

Stack Lifecycle

堆叠分支生命周期

Create stack → Implement features → Submit PRs → Address feedback → Merge
     │              │                  │               │            │
     ▼              ▼                  ▼               ▼            ▼
 gt create     gt modify -acm     gt submit      gt absorb     gt sync

创建堆叠分支 → 实现功能 → 提交PR → 处理反馈 → 合并
     │              │                  │               │            │
     ▼              ▼                  ▼               ▼            ▼
 gt create     gt modify -acm     gt submit      gt absorb     gt sync

Creating Stacks

创建堆叠分支

bash

undefined

bash

undefined

New branch with staged changes

基于已暂存变更创建新分支

gt create 'feature/step-1' -am "feat: first step"

Continue stacking

继续创建堆叠分支

gt create 'feature/step-2' -am "feat: second step" gt create 'feature/step-3' -am "feat: third step"

Insert branch between current and child

在当前分支与子分支之间插入新分支

gt create 'feature/step-1.5' --insert -am "feat: inserted step"

undefined

gt create 'feature/step-1.5' --insert -am "feat: inserted step"

undefined

Navigation

分支导航

Command	Action
`gt up`	Move up the stack (toward children)
`gt down`	Move down the stack (toward parent)
`gt top`	Jump to stack top
`gt bottom`	Jump to stack bottom
`gt checkout`	Interactive branch picker

命令	操作
`gt up`	在堆叠分支中向上移动（指向子分支方向）
`gt down`	在堆叠分支中向下移动（指向父分支方向）
`gt top`	跳转到堆叠分支的最顶层
`gt bottom`	跳转到堆叠分支的最底层
`gt checkout`	交互式分支选择器

Modifying Branches

修改分支

bash

undefined

bash

undefined

Amend current branch (stages all)

修改当前分支（暂存所有变更）

gt modify -a

New commit within same branch

在当前分支创建新提交

gt modify -acm "fix: address review feedback"

Commit to a different branch in the stack

提交变更到堆叠中的其他分支

git add path/to/file.ts gt modify --into target-branch -m "feat: add file"


<rules>

**ALWAYS:**
- Use `gt create` for new branches
- Use `gt modify` for commits
- Use `gt submit` to push
- Use `gt restack` after parent changes
- Check `gt status` when uncertain

**NEVER:**
- Mix `git commit/push/rebase` with `gt` workflows
- Force push without understanding stack state
- Use `git rebase -i` (breaks Graphite metadata)

</rules>

git add path/to/file.ts gt modify --into target-branch -m "feat: add file"


<rules>

**必须遵守：**
- 使用`gt create`创建新分支
- 使用`gt modify`提交变更
- 使用`gt submit`推送变更
- 父分支变更后使用`gt restack`
- 不确定状态时查看`gt status`

**禁止操作：**
- 在`gt`工作流中混合使用`git commit/push/rebase`
- 不了解堆叠分支状态时强制推送
- 使用`git rebase -i`（会破坏Graphite元数据）

</rules>

Addressing Review Feedback

处理评审反馈

Single PR: Navigate to branch, modify directly

bash

gt checkout target-branch
gt modify -acm "fix: address review comment"
gt submit

Multiple PRs in stack: Use absorb from top

bash

gt top
git add .
gt absorb -a
gt submit --stack

Graphite routes changes to correct branches based on file history.

单个PR： 导航到对应分支，直接修改

bash

gt checkout target-branch
gt modify -acm "fix: address review comment"
gt submit

堆叠中的多个PR： 从顶层分支使用absorb命令

bash

gt top
git add .
gt absorb -a
gt submit --stack

Graphite会根据文件历史将变更路由到正确的分支。

Reorganizing Stacks

重组堆叠分支

bash

undefined

bash

undefined

Move branch to different parent

将当前分支移动到新的父分支下

gt move --onto new-parent

Move specific branch

将指定分支移动到目标分支下

gt move --source branch-name --onto target

After reorganization

重组完成后

gt restack

undefined

gt restack

undefined

Submitting

提交PR

bash

undefined

bash

undefined

Current branch + downstack

当前分支及其下方的所有分支

gt submit

Entire stack

整个堆叠分支

gt submit --stack

Non-interactive (automation)

非交互式模式（适用于自动化）

gt submit --no-interactive

undefined

gt submit --no-interactive

undefined

Stack Visualization

堆叠分支可视化

bash

undefined

bash

undefined

JSON with parent relationships (preferred for scripts)

包含父分支关系的JSON格式（适合脚本使用）

gt status

Visual tree

可视化树形结构

gt ls

Recent history

近期提交历史

gt log

undefined

gt log

undefined

Sync and Maintenance

同步与维护

bash

undefined

bash

undefined

Pull trunk, rebase stacks, clean merged

拉取主干分支、变基堆叠分支、清理已合并分支

gt sync

Rebase branches onto updated parents

将分支变基到更新后的父分支

gt restack

Undo last gt operation

撤销上一次gt操作

gt undo

undefined

gt undo

undefined

When Things Go Wrong

故障排查

Stack corruption symptoms:

Branches appear as siblings instead of parent-child
PRs contain wrong files
```
gt status
```
shows unexpected structure

See recovery.md for step-by-step recovery procedures.

commands.md - Quick command reference
recovery.md - Stack corruption recovery

</references>

堆叠分支损坏的症状：

分支显示为同级而非父子关系
PR包含错误的文件
```
gt status
```
显示异常结构

请参考recovery.md获取分步恢复指南。

commands.md - 命令速查手册
recovery.md - 堆叠分支损坏恢复指南

</references>