working-with-graphite

使用 Graphite

核心原则

1. 绝不提交到 main 所有提交都必须位于功能分支上
2. 除非收到要求，否则不要创建分支 除非明确要求，否则不要创建新分支。
3. 绝不使用原始 Git rebase ——始终使用 gt 命令来保留堆栈元数据
4. 提交时始终将 Claude 设为共同作者

分支策略

• 制定计划时，注明每个工作单元预期使用的分支
• 跨越 > 500 LOC 的工作应拆分到多个分支，并将这些分支依次堆叠
• 按逻辑顺序堆叠分支，每个分支包含独立的功能。
• 每个分支都必须通过所有 lint、检查和测试评估

提交代码

• 使用 git 命令手动暂存受影响文件。不要使用 -a 标志自动暂存所有更改。
• 对于新功能，使用 gt modify --commit -m "description of the change" 创建提交
• 对现有功能的修改或错误修复，使用 gt modify 修改提交

提交更改

• 任务完成后，始终运行 gt restack，并确保任何受影响的上游分支仍然有效（lint 检查通过）
• 任务完成后，使用 gt submit --stack --update-only
• 如果更改影响较大，请阅读现有 PR 描述并将更改纳入其中。不要覆盖现有描述，以免丢失重要背景信息。
• 将对 PR 描述所做的任何更改提交给用户审批

创建 PR

• 只有在用户明确同意后，才能提交新的 PR。
• 使用 gt submit --draft 创建 PR。新 PR 始终以草稿形式提交。
• 提交 PR 后，创建详细的 PR 描述，并使用 gh 工具提交
• 提交 PR 描述前，请征求用户批准

处理冲突

在 gt sync、gt restack 或 gt modify 期间发生冲突时：

1. 解决受影响文件中的冲突
2. 暂存已解决的文件：git add <files>
3. 继续：gt continue 或 gt continue --all

工作流：更新堆栈中间的分支

1. gt checkout <target-branch>
2. 进行编辑
3. gt modify -a（修改提交并重新堆叠上游分支）
4. gt submit --stack --update-only --no-interactive（推送所有已更新的分支）

常见注意事项

• 绝不使用 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 解决。