gt

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Graphite

Overview

概述

Graphite (gt) is a CLI tool for managing stacked pull requests - breaking large features into small, incremental changes built on top of each other. This skill provides the mental model, command reference, and workflow patterns needed to work effectively with gt.

Graphite（gt）是一款用于管理堆叠式拉取请求的CLI工具——将大型功能拆分为多个基于彼此构建的小型增量变更。本技能提供了有效使用gt所需的核心思维模型、命令参考和工作流模式。

CRITICAL: Always Use

--no-interactive

重要提示：始终使用

--no-interactive

NEVER invoke any
gt
command without
--no-interactive
. This is a global flag inherited by every gt command — not a per-command option.

Without

--no-interactive

, gt may open prompts, pagers, or editors that hang indefinitely in agent/CI contexts. The

--force

flag does NOT prevent prompts — you must use

--no-interactive

separately.

bash

undefined

**绝对不要在不添加

--no-interactive

的情况下调用任何

gt

命令。**这是所有gt命令都继承的全局标志——而非针对单个命令的选项。

如果不添加

--no-interactive

，gt可能会在Agent/CI环境中打开提示、分页器或编辑器，导致进程无限挂起。

--force

标志无法阻止提示——你必须单独使用

--no-interactive

。

bash

undefined

WRONG - may hang waiting for user input

错误示例 - 可能会因等待用户输入而挂起

gt sync gt submit --force gt track --parent main

CORRECT - always pass --no-interactive

正确示例 - 始终添加--no-interactive

gt sync --no-interactive gt submit --no-interactive gt track --parent main --no-interactive gt restack --no-interactive gt create my-branch -m "message" --no-interactive


**What `--interactive` controls (all disabled by `--no-interactive`):**

- Prompts (confirmation dialogs in sync, delete, submit, etc.)
- Pagers (output paging in log)
- Editors (commit message editing in create/modify, PR metadata in submit)
- Interactive selectors (branch selection in checkout, move, track)

**Note:** `gt modify --interactive-rebase` is a separate, unrelated flag that starts a git interactive rebase. It is NOT the same as the global `--interactive`.

gt sync --no-interactive gt submit --no-interactive gt track --parent main --no-interactive gt restack --no-interactive gt create my-branch -m "message" --no-interactive


**`--interactive`的控制范围（添加`--no-interactive`后会全部禁用）：**

- 提示（同步、删除、提交等操作中的确认对话框）
- 分页器（日志输出的分页功能）
- 编辑器（创建/修改时的提交消息编辑、提交时的PR元数据编辑）
- 交互式选择器（切换、移动、跟踪操作中的分支选择）

**注意：** `gt modify --interactive-rebase`是一个独立的、不相关的标志，用于启动git交互式变基。它与全局的`--interactive`不是同一概念。

Core Mental Model

核心思维模型

Stacks are Linear Chains

栈是线性链

A stack is a sequence of branches where each branch (except trunk) has exactly one parent:

VALID STACK (linear):
main → feature-a → feature-b → feature-c

INVALID (not a stack):
main → feature-a → feature-b
            └─────→ feature-x

栈是一系列分支的序列，其中每个分支（除主干外）恰好有一个父分支：

有效栈（线性）：
main → feature-a → feature-b → feature-c

无效栈（非线性）：
main → feature-a → feature-b
            └─────→ feature-x

Key Concepts

关键概念

Parent-Child Relationships: Every branch tracked by gt (except trunk) has exactly one parent branch it builds upon
Auto-restacking: When modifying a branch, gt automatically rebases all upstack branches to include changes
Directional Navigation:
- Downstack/Down: Toward trunk (toward the base) -
```
gt down
```
  moves from feature-b → feature-a → main
- Upstack/Up: Away from trunk (toward the tip) -
```
gt up
```
  moves from feature-a → feature-b → feature-c
Trunk: The main branch (usually
```
main
```
or
```
master
```
) that all stacks build upon

父子关系：所有被gt跟踪的分支（除主干外）都有一个它所基于的父分支
自动重排栈：当修改一个分支时，gt会自动对所有上游分支执行变基以包含变更
定向导航:
- 下游（Downstack/Down）: 朝向主干（基础方向） -
```
gt down
```
  从feature-b跳转到feature-a再到main
- 上游（Upstack/Up）: 远离主干（顶端方向） -
```
gt up
```
  从feature-a跳转到feature-b再到feature-c
主干（Trunk）: 所有栈所基于的主分支（通常为
```
main
```
或
```
master
```
）

Stack Visualization - CRITICAL MENTAL MODEL

栈可视化 - 核心思维模型

When working with Graphite stacks, always visualize trunk at the BOTTOM:

TOP ↑    feat-3  ← upstack (leaf)
         feat-2
         feat-1
BOTTOM ↓ main    ← downstack (trunk)

使用Graphite栈时，始终要将主干想象在底部：

顶端 ↑    feat-3  ← 上游（叶子节点）
         feat-2
         feat-1
底部 ↓ main    ← 下游（主干）

Directional Terminology - MUST UNDERSTAND

定向术语 - 必须理解

UPSTACK / UP = away from trunk = toward TOP = toward leaves
DOWNSTACK / DOWN = toward trunk = toward BOTTOM = toward main

UPSTACK / UP = 远离主干 = 朝向顶端 = 朝向叶子节点
DOWNSTACK / DOWN = 朝向主干 = 朝向底部 = 朝向main

Detailed Examples

详细示例

Given stack:

main → feat-1 → feat-2 → feat-3

If current branch is
feat-1
:

Upstack:
```
feat-2
```
,
```
feat-3
```
(children, toward top)
Downstack:
```
main
```
(parent, toward bottom)

If current branch is
feat-3
(at top):

Upstack: (nothing, already at top/leaf)
Downstack:
```
feat-2
```
,
```
feat-1
```
,
```
main
```
(ancestors, toward bottom)

给定栈结构：

main → feat-1 → feat-2 → feat-3

如果当前分支是
feat-1
：

上游：
```
feat-2
```
,
```
feat-3
```
（子分支，朝向顶端）
下游：
```
main
```
（父分支，朝向底部）

如果当前分支是
feat-3
（位于顶端）：

上游：（无内容，已处于顶端/叶子节点）
下游：
```
feat-2
```
,
```
feat-1
```
,
```
main
```
（祖先分支，朝向底部）

Why This Mental Model Is Critical

为何此思维模型至关重要

🔴 Commands depend on this visualization:

```
gt up
```
/
```
gt down
```
navigate the stack
```
land-stack
```
traverses branches in specific direction
Stack traversal logic (parent/child relationships)

🔴 Common mistake: Thinking "upstack" means "toward trunk"

WRONG: upstack = toward main ❌
CORRECT: upstack = away from main ✅

🔴 PR landing order: Always bottom→top (main first, then each layer up)

🔴 命令依赖于这种可视化逻辑：

```
gt up
```
/
```
gt down
```
用于导航栈
```
land-stack
```
按特定方向遍历分支
栈遍历逻辑（父子关系）

🔴 常见误区： 认为“上游”是“朝向主干”

错误：上游 = 朝向main ❌
正确：上游 = 远离main ✅

🔴 PR合并顺序： 始终从下到上（先main，然后依次向上每层）

Metadata Storage

元数据存储

All gt metadata is stored in the shared

.git

directory (accessible across worktrees):

```
.git/.graphite_repo_config
```
- Repository-level configuration (trunk branch)
```
.git/.graphite_cache_persist
```
- Branch relationships (parent-child graph)
```
.git/.graphite_pr_info
```
- Cached GitHub PR information

Important: Metadata is shared across all worktrees since it's in the common

.git

directory.

所有gt元数据都存储在共享的

.git

目录中（可跨工作树访问）：

```
.git/.graphite_repo_config
```
- 仓库级配置（主干分支）
```
.git/.graphite_cache_persist
```
- 分支关系（父子图）
```
.git/.graphite_pr_info
```
- 缓存的GitHub PR信息

重要提示：由于元数据存储在公共的

.git

目录中，因此它会在所有工作树之间共享。

Essential Commands

必备命令

Remember: ALL gt commands below must include
--no-interactive
(see CRITICAL: Always Use

--no-interactive

above).

记住：以下所有gt命令都必须添加
--no-interactive
（参见上方重要提示：始终使用

--no-interactive

部分）。

Common Workflow Commands

常见工作流命令

Command	Alias	Purpose
`gt create [name]`	`gt c`	Create new branch stacked on current branch and commit staged changes
`gt modify`	`gt m`	Modify current branch (amend commit) and auto-restack children
`gt submit`	`gt s`	Push branches and create/update PRs
`gt submit --stack`	`gt ss`	Submit entire stack (up + down)
`gt sync`	-	Sync from remote and prompt to delete merged branches

命令	别名	用途
`gt create [name]`	`gt c`	创建基于当前分支的新分支，并提交暂存的变更
`gt modify`	`gt m`	修改当前分支（修正提交）并自动重排上游子分支
`gt submit`	`gt s`	推送分支并创建/更新PR
`gt submit --stack`	`gt ss`	提交整个栈（上游+下游）
`gt sync`	-	从远程同步，并提示删除已合并的分支

Navigation Commands

导航命令

Command	Alias	Purpose
`gt up [steps]`	`gt u`	Move up stack (away from trunk)
`gt down [steps]`	`gt d`	Move down stack (toward trunk)
`gt top`	`gt t`	Move to tip of stack
`gt bottom`	`gt b`	Move to bottom of stack
`gt checkout [branch]`	`gt co`	Interactive branch checkout

命令	别名	用途
`gt up [steps]`	`gt u`	向上游导航栈（远离主干）
`gt down [steps]`	`gt d`	向下游导航栈（朝向主干）
`gt top`	`gt t`	跳转到栈的顶端
`gt bottom`	`gt b`	跳转到栈的底部
`gt checkout [branch]`	`gt co`	交互式切换分支

Stack Management

栈管理

Command	Purpose
`gt restack`	Ensure each branch has its parent in git history
`gt move`	Rebase current branch onto different parent
`gt fold`	Fold branch's changes into parent
`gt split`	Split current branch into multiple single-commit branches
`gt log`	Visualize stack structure

命令	用途
`gt restack`	确保每个分支的父分支都在git历史中
`gt move`	将当前分支变基到不同的父分支上
`gt fold`	将分支的变更合并到父分支中
`gt split`	将当前分支拆分为多个单提交分支
`gt log`	可视化栈结构

Branch Info & Management

分支信息与管理

Command	Purpose
`gt branch info`	Show branch info (parent, children, commit SHA)
`gt parent`	Show parent branch name
`gt children`	Show children branch names
`gt track [branch]`	Start tracking branch with gt (set parent)
`gt untrack [branch]`	Stop tracking branch with gt
`gt delete [name]`	Delete branch and update metadata
`gt rename [name]`	Rename branch and update metadata

命令	用途
`gt branch info`	显示分支信息（父分支、子分支、提交SHA）
`gt parent`	显示父分支名称
`gt children`	显示子分支名称
`gt track [branch]`	开始用gt跟踪分支（设置父分支）
`gt untrack [branch]`	停止用gt跟踪分支
`gt delete [name]`	删除分支并更新元数据
`gt rename [name]`	重命名分支并更新元数据

Workflow Patterns

工作流模式

Pattern 1: Creating a New Stack

模式1：创建新栈

Build a feature in multiple reviewable chunks:

bash

undefined

将功能拆分为多个可评审的小块：

bash

undefined

1. Start from trunk

1. 从主干开始

gt checkout main --no-interactive git pull

2. Create first branch

2. 创建第一个分支

gt create phase-1 -m "Add API endpoints" --no-interactive

... make changes ...

... 进行变更 ...

git add . gt modify -m "Add API endpoints" --no-interactive

3. Create second branch on top

3. 在顶部创建第二个分支

gt create phase-2 -m "Update frontend" --no-interactive

... make changes ...

... 进行变更 ...

git add . gt modify -m "Update frontend" --no-interactive

4. Submit entire stack

4. 提交整个栈

gt submit --stack --no-interactive

Result: 2 PRs created

结果：创建2个PR

PR #101: phase-1 (base: main)

PR #101: phase-1（基础：main）

PR #102: phase-2 (base: phase-1)

PR #102: phase-2（基础：phase-1）

undefined

undefined

Pattern 2: Responding to Review Feedback

模式2：响应评审反馈

Update a branch in the middle of a stack:

bash

undefined

更新栈中间的某个分支：

bash

undefined

Navigate down to target branch

导航到目标分支

gt down --no-interactive # Repeat as needed

gt down --no-interactive # 根据需要重复执行

Make changes

进行变更

... edit files ...

... 编辑文件 ...

git add .

Modify (auto-restacks upstack branches)

修改分支（自动重排上游子分支）

gt modify -m "Address review feedback" --no-interactive

Resubmit stack

重新提交栈

gt submit --stack --no-interactive

undefined

gt submit --stack --no-interactive

undefined

Pattern 3: Adding to Existing Stack

模式3：向现有栈中添加内容

Insert a new branch in the middle:

bash

undefined

在栈中间插入新分支：

bash

undefined

Checkout the parent where you want to insert

切换到要插入位置的父分支

gt checkout phase-1 --no-interactive

Create new branch with --insert

使用--insert创建新分支

gt create phase-1.5 --insert -m "Add validation" --no-interactive

Submit new PR

提交新PR

gt submit --no-interactive

undefined

gt submit --no-interactive

undefined

Pattern 4: Syncing After Merges

模式4：合并后同步

Clean up after PRs merge on GitHub:

bash

undefined

在GitHub上合并PR后清理本地环境：

bash

undefined

Run sync (--no-interactive auto-confirms branch deletion)

执行同步（--no-interactive会自动确认分支删除）

gt sync --no-interactive

Result:

结果：

- Merged branches deleted locally

- 已合并的分支被本地删除

- Remaining branches rebased onto trunk

- 剩余分支被变基到主干

- PR bases updated on GitHub

- GitHub上的PR基础分支被更新

undefined

undefined

Pattern 5: Splitting Large Changes

模式5：拆分大型变更

Break up a large commit into reviewable pieces:

bash

undefined

将大型提交拆分为多个可评审的部分：

bash

undefined

Checkout branch with large commit

切换到包含大型提交的分支

gt checkout large-feature --no-interactive

Split into single-commit branches

拆分为多个单提交分支

gt split --no-interactive

Rename branches meaningfully

给分支赋予有意义的名称

gt rename add-api-endpoints --no-interactive gt up --no-interactive gt rename add-frontend --no-interactive gt up --no-interactive gt rename add-tests --no-interactive

Submit

提交

gt submit --stack --no-interactive

undefined

gt submit --stack --no-interactive

undefined

Common Mistakes to Avoid

需避免的常见错误

Don't use
git rebase
directly: Use
```
gt modify
```
or
```
gt restack
```
- gt needs to update metadata during rebasing
Don't delete branches with
git branch -d
: Use
```
gt delete
```
- metadata needs to be updated to re-parent children
Don't assume
gt submit
only affects current branch: It submits downstack too (all ancestors). Use
```
gt submit --stack
```
to include upstack
Don't forget to
gt sync
after merges: Stale branches accumulate and metadata gets outdated
⚠️ NEVER use
gt log short
for branch status: The output format is counterintuitive and confuses agents. Use
```
gt branch info
```
,
```
gt parent
```
, or
```
gt children
```
for explicit metadata access instead

不要直接使用
git rebase
：使用
```
gt modify
```
或
```
gt restack
```
——gt需要在变基过程中更新元数据
不要用
git branch -d
删除分支：使用
```
gt delete
```
——需要更新元数据来重新设置子分支的父分支
不要假设
gt submit
只影响当前分支：它也会提交下游分支（所有祖先分支）。使用
```
gt submit --stack
```
来包含上游分支
合并后不要忘记执行
gt sync
：过时的分支会堆积，元数据也会失效
⚠️ 绝对不要用
gt log short
查看分支状态：输出格式违反直觉，会混淆Agent。请改用
```
gt branch info
```
、
```
gt parent
```
或
```
gt children
```
来明确获取元数据

Quick Decision Tree

快速决策树

When to use gt commands:

Start new work →
```
gt create
```
(sets parent relationship)
Edit current branch →
```
gt modify
```
(auto-restacks children)
Navigate stack →
```
gt up/down/top/bottom
```
(move through chain)
View structure →
```
gt log
```
(see visualization)
Get parent branch →
```
gt branch info
```
(parse "Parent:" line)
Get branch relationships →
```
gt parent
```
/
```
gt children
```
(quick access)
Submit PRs →
```
gt submit --stack
```
(create/update all PRs)
After merges →
```
gt sync
```
(clean up + rebase)
Reorganize →
```
gt move
```
(change parent)
Combine work →
```
gt fold
```
(merge into parent)
Split work →
```
gt split
```
(break into branches)

何时使用gt命令：

开始新工作 →
```
gt create
```
（设置父子关系）
编辑当前分支 →
```
gt modify
```
（自动重排子分支）
导航栈 →
```
gt up/down/top/bottom
```
（在链中跳转）
查看结构 →
```
gt log
```
（查看可视化图）
获取父分支 →
```
gt branch info
```
（解析“Parent:”行）
获取分支关系 →
```
gt parent
```
/
```
gt children
```
（快速访问）
提交PR →
```
gt submit --stack
```
（创建/更新所有PR）
合并后 →
```
gt sync
```
（清理+变基）
重新组织 →
```
gt move
```
（修改父分支）
合并工作 →
```
gt fold
```
（合并到父分支）
拆分工作 →
```
gt split
```
（拆分为多个分支）

Resources

资源

references/

Contains detailed command reference and comprehensive mental model documentation:

```
gt-reference.md
```
- Complete command reference, metadata format details, and advanced patterns

Load this reference when users need detailed information about specific gt commands, metadata structure, or complex workflow scenarios.

包含详细的命令参考和全面的思维模型文档：

```
gt-reference.md
```
- 完整的命令参考、元数据格式细节和高级模式

当用户需要特定gt命令、元数据结构或复杂工作流场景的详细信息时，可加载此参考文档。

gt

Original

Translation

Graphite

Graphite

Overview

概述

CRITICAL: Always Use --no-interactive

重要提示：始终使用--no-interactive

WRONG - may hang waiting for user input

错误示例 - 可能会因等待用户输入而挂起

CORRECT - always pass --no-interactive

正确示例 - 始终添加--no-interactive

Core Mental Model

核心思维模型

Stacks are Linear Chains

栈是线性链

Key Concepts

关键概念

Stack Visualization - CRITICAL MENTAL MODEL

栈可视化 - 核心思维模型

Directional Terminology - MUST UNDERSTAND

定向术语 - 必须理解

Detailed Examples

详细示例

Why This Mental Model Is Critical

为何此思维模型至关重要

Metadata Storage

元数据存储

Essential Commands

必备命令

Common Workflow Commands

常见工作流命令

Navigation Commands

导航命令

Stack Management

栈管理

Branch Info & Management

分支信息与管理

Workflow Patterns

工作流模式

Pattern 1: Creating a New Stack

模式1：创建新栈

1. Start from trunk

1. 从主干开始

2. Create first branch

2. 创建第一个分支

... make changes ...

... 进行变更 ...

3. Create second branch on top

3. 在顶部创建第二个分支

... make changes ...

... 进行变更 ...

4. Submit entire stack

4. 提交整个栈

Result: 2 PRs created

结果：创建2个PR

PR #101: phase-1 (base: main)

PR #101: phase-1（基础：main）

PR #102: phase-2 (base: phase-1)

PR #102: phase-2（基础：phase-1）

Pattern 2: Responding to Review Feedback

模式2：响应评审反馈

Navigate down to target branch

导航到目标分支

Make changes

进行变更

... edit files ...

... 编辑文件 ...

Modify (auto-restacks upstack branches)

修改分支（自动重排上游子分支）

Resubmit stack

重新提交栈

Pattern 3: Adding to Existing Stack

模式3：向现有栈中添加内容

Checkout the parent where you want to insert

切换到要插入位置的父分支

Create new branch with --insert

使用--insert创建新分支

Submit new PR

CRITICAL: Always Use
`--no-interactive`

重要提示：始终使用
`--no-interactive`