graphite-stacks

Graphite 堆栈

使用 Graphite CLI 进行主干开发，并采用堆叠 PR。

<when_to_use>

• 创建或管理分支堆栈
• 提交堆叠 PR
• 重新组织分支关系
• 处理整个堆栈中的 PR 反馈
• 从堆栈损坏中恢复
• 使用任何 gt 命令

</when_to_use>

核心原则

只使用 gt 命令。 混用 git 和 gt 会导致同步问题和堆栈分歧。唯一例外：使用 git add 暂存更改（或使用 -a 标志）。

用这个，不用那个

任务	用这个	不用那个
创建分支	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	手动 Cherry-pick 提交

堆栈生命周期

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

创建堆栈

# 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"

导航

命令	操作
gt up	沿堆栈向上移动（朝向子分支）
gt down	沿堆栈向下移动（朝向父分支）
gt top	跳转到堆栈顶部
gt bottom	跳转到堆栈底部
gt checkout	交互式选择分支

修改分支

# 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"

始终：

• 使用 gt create 创建新分支
• 使用 gt modify 创建提交
• 使用 gt submit 推送
• 更改父分支后使用 gt restack
• 不确定时检查 gt status

绝不：

• 在 gt 工作流中混用 git commit/push/rebase
• 不了解堆栈状态就强制推送
• 使用 git rebase -i（会破坏 Graphite 元数据）

处理评审反馈

单个 PR：切换到对应分支，直接修改

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

堆栈中的多个 PR：从顶部使用 absorb

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

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

重新组织堆栈

# Move branch to different parent
gt move --onto new-parent

# Move specific branch
gt move --source branch-name --onto target

# After reorganization
gt restack

提交

# Current branch + downstack
gt submit

# Entire stack
gt submit --stack

# Non-interactive (automation)
gt submit --no-interactive

堆栈可视化

# JSON with parent relationships (preferred for scripts)
gt status

# Visual tree
gt ls

# Recent history
gt log

同步与维护

# Pull trunk, rebase stacks, clean merged
gt sync

# Rebase branches onto updated parents
gt restack

# Undo last gt operation
gt undo

出现问题时

堆栈损坏的表现：

• 分支显示为兄弟分支，而非父子分支
• PR 中包含错误的文件
• gt status 显示意外的结构

请参阅 recovery.md，了解逐步恢复流程。

• commands.md - 命令快速参考
• recovery.md - 堆栈损坏恢复