GraphiteCLI指南Skill graphite-cli

Graphite CLI指南

这个技能提供了使用Graphite命令行界面（CLI）的工作程序知识。它涵盖了从初始设置到高级堆栈操作的整个生命周期，用于创建和管理堆叠的拉取请求。

何时使用此技能

当用户的请求涉及使用gt命令、管理堆叠拉取请求或询问Graphite工作流时，激活此技能。它旨在处理创建分支、提交PR、与主干分支同步以及修改堆栈结构等任务。

---

I.初始设置

要开始在git仓库中使用Graphite，必须先进行初始化。

1. **认证：**运行gt auth，通过auth token将CLI连接到您的GitHub账户。
2. **初始化仓库：**导航到仓库根目录并运行gt init。此命令将提示选择主干分支。

---

II.核心工作流：创建和提交更改

这个工作流涵盖了创建、提交和更新分支的基本循环。

第1步：创建分支

要创建新分支并提交更改，请使用gt create。此命令替换了git add、git commit和git checkout -b。新分支将堆叠在当前检出的分支上。

命令	别名/标志	描述
gt create	gt c	创建新分支并提交已暂存的更改。
gt create -m <MSG>	gt c -m	使用特定的提交消息创建分支。
gt create -a	gt c -a	在提交前暂存所有未暂存的更改。
gt create -am <MSG>	gt c -am	结合暂存所有更改并添加消息。

示例： 要从main创建分支，并带有所有当前文件更改和提交消息：

1. 检出主干：gt checkout main
2. 进行代码编辑。
3. 创建分支：gt create -am "feat: 添加新用户模型"

第2步：提交审核

要推送分支（或分支堆栈）并在GitHub上打开拉取请求，请使用gt submit。

命令	别名/标志	描述
gt submit		推送当前分支，创建或更新其PR。
gt submit --stack	gt ss	推送当前堆栈中的所有分支，从主干到当前分支，为每个分支创建/更新一个不同的PR。
gt submit -d		将PR作为草稿提交。
gt pr		在浏览器中打开当前分支的GitHub PR页面。

示例： 要提交整个3部分堆栈进行审核：

1. 导航到堆栈的顶部分支（part-3）。
2. 运行gt submit --stack --reviewers alice,bob

第3步：修改和更新

要使用反馈更新分支，编辑代码并使用gt modify来修改提交。

命令	别名/标志	描述
gt modify	gt m	使用暂存的更改修改当前分支上的提交。
gt modify -a	gt m -a	使用所有暂存和未暂存的更改修改提交。这是最常见的更新命令。

示例： 要对PR应用请求的更改：

1. 编辑相关文件。
2. 运行gt modify -a，用您的更改修改提交。
3. 运行gt submit更新远程PR。

---

III.堆栈管理与导航

可视化堆栈

要查看分支的依赖结构，请使用gt log short。

命令	别名	描述
gt log short	gt ls	以紧凑的树形格式显示所有跟踪的分支及其依赖关系。

导航堆栈

使用这些命令在堆栈中的分支之间高效移动。

命令	别名	功能
gt up	gt u	切换到子分支（上堆栈）。
gt down	gt d	切换到父分支（下堆栈）。
gt top	gt t	切换到当前堆栈的最高分支（尖端）。
gt bottom	gt b	切换到当前堆栈的最低分支。
gt checkout	gt co	打开交互式选择器以选择任何跟踪的分支。

---

IV.同步与冲突解决

保持堆栈最新

要使用主干的最新更改更新您的堆栈，请使用gt sync。

gt sync执行的操作：

1. 获取最新的远程状态。
2. 将最新更改拉取到主干分支（main）。
3. 重新堆叠（重新基线）所有开放的分支到更新的主干上。
4. 提示删除任何已合并或远程关闭的本地分支。

解决冲突

如果gt sync或gt modify因合并冲突而暂停，请按照以下步骤操作：

1. **解决冲突：**打开错误消息中列出的文件，并手动解决冲突。
2. **暂存更改：**通过运行git add .将冲突标记为已解决。
3. **继续：**运行gt continue，允许Graphite完成原始的sync或modify操作。

---

V.高级堆栈操作

这些命令用于重构堆栈。

命令	描述
gt move	将当前分支及其子分支重新基线到新的父分支上。使用此命令更改分支的依赖性（例如，gt move --onto main）。
gt fold	将当前分支的更改合并（压缩）到其父分支，并删除当前分支。
gt split	将当前分支拆分为两个或更多新分支，可以按提交或通过交互式选择文件块来拆分。
gt create --insert	在当前分支和其父分支之间创建并插入一个新分支。
gt absorb	自动将未暂存的更改应用到最相关的下堆栈提交中。对于一次性将反馈修复分发到多个PR非常有用。

---

捆绑资源

• references/graphite_cli_guide.md：Graphite CLI的完整和未删节指南。查阅此文件以获取每个命令和工作流的详细解释，包括协作（gt get，gt freeze）和多主干支持。