graphite

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Graphite (gt) Skill

Graphite（gt）操作指南

This skill provides instructions for navigating branches and restacking stacks using Graphite (

gt

本指南提供了使用Graphite（

gt

）进行分支导航和栈重排的操作说明。

Core Principles

核心原则

Strictly Prohibited: NEVER run
```
gt ss
```
,
```
gt submit
```
, or
```
gt squash
```
. These commands are forbidden.
Navigation: Use
```
gt
```
commands to move between branches in a stack.
Maintenance: Use
```
gt restack
```
for local stack maintenance and
```
gt get
```
or
```
gt sync
```
for syncing from remote.

严格禁止：绝对不要运行
```
gt ss
```
、
```
gt submit
```
或
```
gt squash
```
命令，这些命令被禁用。
导航：使用
```
gt
```
命令在栈中的各个分支间切换。
维护：使用
```
gt restack
```
进行本地栈维护，使用
```
gt get
```
或
```
gt sync
```
与远程仓库同步。

Branch Navigation

分支导航

Use these commands to navigate through a stack of branches:

Command	Action
`gt up`	Move to the branch immediately above the current one in the stack.
`gt down`	Move to the parent of the current branch.
`gt prev`	Move to the previous branch in the stack, as ordered by `gt log` .
`gt next`	Move to the next branch in the stack, as ordered by `gt log` .
`gt top`	Move to the tip branch of the current stack.
`gt bottom`	Move to the branch closest to trunk in the current stack.
`gt ls`	Display all tracked branches and their dependency relationships in a short format.

使用以下命令在分支栈中进行导航：

命令	操作
`gt up`	切换到当前栈中位于当前分支的上一级分支。
`gt down`	切换到当前分支的父分支。
`gt prev`	切换到当前栈中 `gt log` 排序里的上一个分支。
`gt next`	切换到当前栈中 `gt log` 排序里的下一个分支。
`gt top`	切换到当前栈的最顶端分支。
`gt bottom`	切换到当前栈中最接近主分支（trunk）的分支。
`gt ls`	以简洁格式显示所有被追踪的分支及其依赖关系。

Stack Management

栈管理

Maintain your stack with these commands:

Command	Action
`gt restack`	Ensure each branch in the current stack has its parent in its Git commit history, rebasing if necessary. This maintains the local stack and does NOT reach out to upstream.
`gt get`	Sync a specific branch or stack from remote (trunk to branch). If no branch is provided, it syncs the current stack.
`gt sync`	Sync all branches (including trunk) from remote and prompt to delete merged branches.

使用以下命令维护你的分支栈：

命令	操作
`gt restack`	确保当前栈中的每个分支的父分支都存在于其Git提交历史中，必要时执行变基操作。该命令仅维护本地栈，不会与上游仓库交互。
`gt get`	从远程仓库同步指定分支或栈（从主分支到目标分支）。若未指定分支，则同步当前栈。
`gt sync`	从远程仓库同步所有分支（包括主分支），并提示删除已合并的分支。

Branch Management

分支管理

Use these commands to manage branches within your stack.

Command	Action
`gt create <branch-name>`	Create a new branch with the given name and stack it on top of the current one. Always follow the `/gt-create` workflow.
`gt move`	Rebase the current branch onto a target branch and restack descendants. Use `--onto <target-branch>` to avoid interactive mode.
`gt split`	Split the current branch into multiple branches. This command is highly interactive.

使用以下命令管理栈中的分支。

命令	操作
`gt create <branch-name>`	创建一个指定名称的新分支，并将其堆叠在当前分支之上。务必遵循 `/gt-create` 工作流。
`gt move`	将当前分支变基到目标分支上，并重新堆叠其子分支。使用 `--onto <target-branch>` 参数可避免进入交互模式。
`gt split`	将当前分支拆分为多个分支。该命令具有高度交互性。

Commit Management

提交管理

Use

gt modify

to manage commits within your stack. It automatically restacks descendants.

Command	Action
`gt modify --amend`	Amend the head commit of the current branch.
`gt modify -c`	Create a new commit on the current branch. Preferred for adding new changes while keeping history clean.

使用

gt modify

管理栈中的提交，它会自动重新堆叠子分支。

命令	操作
`gt modify --amend`	修改当前分支的最新提交。
`gt modify -c`	在当前分支上创建一个新提交。推荐使用此方式添加新更改，同时保持提交记录整洁。

Dealing with Interactivity

处理交互模式

Many Graphite commands (

gt modify

gt move

gt split

gt restack

) are interactive by default, opening selectors, editors, or specialized menus.

For the Agent: Avoid using these commands in an interactive way. If a command requires user input that cannot be provided via flags (e.g., resolving complex rebase conflicts), stop and notify the user.
Rebase Conflicts: If
```
gt restack
```
or
```
gt move
```
hits a conflict, Graphite will pause. Follow these steps to resolve:
1. Locate Conflicts: Use
```
git status
```
  or look at the error output to identify files with merge conflicts.
2. Edit Files: Open the conflicting files and resolve the merge markers (
```
<<<<<<<
```
  ,
```
=======
```
  ,
```
>>>>>>>
```
  ). Ensure the code is functionally correct and includes necessary changes from both sides.
3. Stage Changes: Run
```
gt add -A
```
  (or
```
git add <file>
```
  ) to mark the conflicts as resolved.
4. Continue: Run
```
gt continue
```
  to resume the restack process. IMPORTANT: NEVER use
```
git rebase --continue
```
  as Graphite tracks its own state.
5. Verify: Once the restack completes, run tests to ensure the merged state is stable.
Interactive Selectors: Prefer providing explicit branch names or flags (like
```
--onto
```
for
```
gt move
```
) to avoid interactive selectors.

许多Graphite命令（

gt modify

、

gt move

、

gt split

、

gt restack

）默认是交互模式，会打开选择器、编辑器或专用菜单。

对于Agent：避免以交互方式使用这些命令。如果命令需要无法通过参数提供的用户输入（例如解决复杂的变基冲突），请停止操作并通知用户。
变基冲突：如果
```
gt restack
```
或
```
gt move
```
遇到冲突，Graphite会暂停。请按照以下步骤解决：
1. 定位冲突：使用
```
git status
```
  或查看错误输出，找出存在合并冲突的文件。
2. 编辑文件：打开冲突文件，解决合并标记（
```
<<<<<<<
```
  、
```
=======
```
  、
```
>>>>>>>
```
  ）。确保代码功能正确，同时包含双方的必要更改。
3. 暂存更改：运行
```
gt add -A
```
  （或
```
git add <file>
```
  ）标记冲突已解决。
4. 继续操作：运行
```
gt continue
```
  恢复栈重排过程。重要提示：绝对不要使用
```
git rebase --continue
```
  ，因为Graphite会追踪自身的状态。
5. 验证：栈重排完成后，运行测试确保合并后的状态稳定。
交互选择器：优先提供明确的分支名称或参数（例如
```
gt move
```
的
```
--onto
```
参数），避免使用交互选择器。

Common Fixes & Lessons

常见问题修复与经验总结

Using Graphite over Git

使用Graphite而非Git原生命令

The Problem: Using standard

git commit

git commit --amend

fails to update Graphite's internal stack metadata and does not trigger automatic restacking of descendants. This can lead to a desynchronized stack where Graphite is unaware of the new commits or changes.

The Solution: Always prefer

gt

commands over their standard

git

counterparts for commit and branch management.

Creating a new branch: Use

gt create <branch-name>

instead of

git checkout -b <branch-name>

Creating a new commit: Use

gt modify -c -m "message"

instead of

git commit -m "message"

Amending a commit: Use
```
gt modify --amend
```
instead of
```
git commit --amend
```
.
Staging and committing everything: Use
```
gt modify -cam "message"
```
instead of
```
git commit -am "message"
```
.

Benefits:

Metadata Integrity: Graphite keeps its internal view of the stack consistent.
Automatic Restacking: Descendant branches are automatically updated if you change a parent branch.
Visual Clarity: Graphite's CLI output stays accurate and helpful.

问题：使用标准的

git commit

或

git commit --amend

不会更新Graphite的内部栈元数据，也不会自动重新堆叠子分支。这会导致栈不同步，Graphite无法感知新的提交或更改。

解决方案：在进行提交和分支管理时，始终优先使用

gt

命令而非Git原生命令。

创建新分支：使用

gt create <branch-name>

而非

git checkout -b <branch-name>

。

创建新提交：使用

gt modify -c -m "提交信息"

而非

git commit -m "提交信息"

。

修改提交：使用
```
gt modify --amend
```
而非
```
git commit --amend
```
。

暂存并提交所有更改：使用

gt modify -cam "提交信息"

而非

git commit -am "提交信息"

。

优势:

元数据完整性：Graphite对栈的内部视图保持一致。
自动重排：若你修改了父分支，子分支会自动更新。
视觉清晰度：Graphite的CLI输出始终准确且有帮助。

Misplaced Commits

提交位置错误

If you accidentally commit a change to the wrong branch in a stack:

Stash uncommitted changes: If you have uncommitted work,
```
git stash
```
to keep it safe.
Move the change to a new branch (if the commit belongs in its own new branch):
1. ```
gt create <new-branch>
```
  to safely move the head.
2. ```
gt down
```
  to move back to the parent.
3. ```
git reset --hard HEAD~1
```
  (Safe now because the commit is preserved in the new branch).
Move to an existing branch:
1. ```
git reset HEAD~1
```
  (Soft reset to keep changes in the working tree).
2. ```
gt down
```
  /
```
gt up
```
  to the target branch.
3. ```
gt modify -c
```
  or
```
gt modify --amend
```
  to incorporate the changes.
Restore stashed changes:
```
git stash pop
```
to resume your work.
Repair the stack: Move back to the tip and run
```
gt restack
```
to ensure all descendant branches are updated with the parent's new state.

如果你不小心将更改提交到了栈中的错误分支：

暂存未提交的更改：若有未提交的工作，使用
```
git stash
```
保存。
将更改移动到新分支（如果该提交应属于一个新分支）：
1. 运行
```
gt create <new-branch>
```
  以安全移动最新提交。
2. 运行
```
gt down
```
  回到父分支。
3. 运行
```
git reset --hard HEAD~1
```
  （现在操作是安全的，因为提交已保留在新分支中）。
移动到现有分支:
1. 运行
```
git reset HEAD~1
```
  （软重置，将更改保留在工作区）。
2. 使用
```
gt down
```
  /
```
gt up
```
  切换到目标分支。
3. 使用
```
gt modify -c
```
  或
```
gt modify --amend
```
  合并更改。
恢复暂存的更改：运行
```
git stash pop
```
继续你的工作。
修复栈：切换到栈的顶端分支，运行
```
gt restack
```
确保所有子分支都已更新为父分支的新状态。

Prohibited Commands

禁止使用的命令

[!CAUTION] DO NOT use the following commands under any circumstances:
gt ss
gt submit
gt squash

These commands are strictly forbidden to ensure that PR submission, updates, and branch squashing are handled manually or through specified workflows.

[!CAUTION] 绝对不要在任何情况下使用以下命令：
gt ss
gt submit
gt squash

这些命令被严格禁用，以确保PR提交、更新和分支合并操作通过手动方式或指定工作流处理。