working-with-graphite

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Working with Graphite

使用Graphite

Core Principles

核心原则

Never commit to main All commits must be on a feature branch
Do not create branches unless asked Do not create new branches unless explicitly requested to.
Never use raw Git rebase -- always use
```
gt
```
commands to preserve stack metadata
Always set Claude as the co-author when committing

永远不要向main分支提交代码 所有提交都必须在功能分支上
未经要求不要创建分支 除非明确要求，否则不要创建新分支。
永远不要使用原生Git rebase -- 请始终使用
```
gt
```
命令以保留栈元数据
提交代码时始终将Claude设为共同作者

Branch Strategy

分支策略

When creating plans, include the expected branches for each unit of work
Pieces of work that span > 500 LOC should be broken into multiple branches and stacked onto one another
Stack branches in a logical order, with discrete features in each branch.
Each branch must be able to pass all lint, check, and test evaluations

制定计划时，需为每个工作单元规划对应的分支
代码量超过500行的工作内容应拆分为多个分支，并堆叠在一起
按照逻辑顺序堆叠分支，每个分支对应独立的功能点
每个分支必须能通过所有lint检查、代码校验和测试评估

Committing code

提交代码

Manually stage changes to impacted files using git commands. Do not use the
```
-a
```
flag to automatically stage all changes.

For new features, create a commit using

gt modify --commit -m "description of the change"

For modifications to an existing feature or bug fixes, amend the commit using
```
gt modify
```

使用Git命令手动暂存受影响文件的变更。不要使用
```
-a
```
参数自动暂存所有变更。
开发新功能时，使用
```
gt modify --commit -m "变更描述"
```
创建提交
对现有功能进行修改或修复Bug时，使用
```
gt modify
```
修改提交

Submitting Changes

提交变更

When the task is complete, always
```
gt restack
```
and ensure that any impacted upstack branches are still valid (lint checks pass)
Use
```
gt submit --stack --update-only
```
when tasks are complete
If the changes are material, read the existing PR description and incorporate the changes. Do not overwrite the existing description losing important context.
Present any changes to the PR description to the user for approval

任务完成后，务必执行
```
gt restack
```
，并确保所有受影响的上游分支仍然有效（通过lint检查）
任务完成时，使用
```
gt submit --stack --update-only
```
命令
如果变更内容较为重要，需阅读现有PR描述并整合变更内容。不要覆盖现有描述，以免丢失重要上下文信息。
将PR描述的任何修改提交给用户审批

Creating PR's

创建PR

Only submit a new PR with the user's explicit consent.
Create the PR with
```
gt submit --draft
```
. Always submit new PR's as a draft.
After submitting the PR, create a detailed PR description and submit it using the
```
gh
```
tool
Ask the user for approval before submitting the PR description

仅在用户明确同意的情况下提交新的PR
使用
```
gt submit --draft
```
创建PR。所有新PR都必须以草稿形式提交。
提交PR后，编写详细的PR描述并通过
```
gh
```
工具提交
提交PR描述前需征得用户同意

Handling Conflicts

处理冲突

When conflicts occur during

gt sync

gt restack

, or

gt modify

Resolve conflicts in affected files
Stage resolved files:
```
git add <files>
```
Continue:
```
gt continue
```
or
```
gt continue --all
```

当在

gt sync

、

gt restack

或

gt modify

操作中出现冲突时：

解决受影响文件中的冲突
暂存已解决的文件：
```
git add <files>
```
继续执行：
```
gt continue
```
或
```
gt continue --all
```

Workflow: Updating a Mid-Stack Branch

工作流：更新中间栈分支

```
gt checkout <target-branch>
```
Make edits
```
gt modify -a
```
(amends and restacks upstack)

gt submit --stack --update-only --no-interactive

(pushes all updated branches)

```
gt checkout <目标分支>
```
进行修改
```
gt modify -a
```
（修改提交并重新堆叠上游分支）

gt submit --stack --update-only --no-interactive

（推送所有已更新的分支）

Common Gotchas

常见注意事项

Never
git rebase -i
-- breaks Graphite metadata. Use
```
gt move
```
instead.
Never
git branch -d
-- use
```
gt delete
```
to preserve metadata.
Never
git commit --amend
-- use
```
gt modify -a
```
which also restacks.
gt rename
breaks PR links -- avoid renaming branches with existing PRs.
Squash merges cause cascading conflicts --
```
gt sync
```
+
```
gt restack
```
resolves this.

永远不要使用
git rebase -i
-- 这会破坏Graphite的元数据，请改用
```
gt move
```
。
永远不要使用
git branch -d
-- 请使用
```
gt delete
```
以保留元数据。
永远不要使用
git commit --amend
-- 请使用
```
gt modify -a
```
，该命令同时会重新堆叠分支。
gt rename
会破坏PR链接 -- 避免重命名已有PR关联的分支。
合并压缩会引发连锁冲突 -- 使用
```
gt sync
```
+
```
gt restack
```
可解决此问题。