用途
该技能用于完成 GitButler 虚拟分支的收尾与集成：当虚拟分支的工作已完成、准备发布时，将其合并到 main 分支并清理。触发场景包括用户要求“完成分支”“合并到 main”“完成我的功能”“发布此分支”“集成到 main”等。
不适用场景：仍在进行中的工作、需要继续开发的分支、堆叠分支（需自底向上完成）。
主要能力
- 集成前检查清单：确认 GitButler 运行（but --version）、工作已提交（but status）、测试通过、基础分支已更新（but pull）、已创建快照（but oplog snapshot）。
- 三种集成工作流：
- A. 使用 CLI（首选）：but oplog snapshot -> but push <branch> -> but pr new <branch> -> 在 GitHub 合并 PR -> but branch delete <branch>。
- B. 直接合并到 main：but oplog snapshot -> git checkout main -> git pull -> git merge --no-ff refs/gitbutler/<branch> -> git push -> but branch delete <branch> -> git checkout gitbutler/workspace。
- C. 手动 PR 工作流：git push origin refs/gitbutler/<branch>:refs/heads/<branch> -> gh pr create -> 合并 PR -> 清理。
- 堆叠分支（自底向上）：必须按 base → dependent → final 的顺序合并，每层合并后执行 but pull 更新剩余分支。
- 错误恢复：合并冲突（git status、手动解决、git add、git commit、git push）、推送被拒（git pull origin main 后重新推送）、撤销集成（未推送用 git reset --hard HEAD~1；已推送用 git revert -m 1 HEAD）。
- 集成后清理：but branch delete <branch>、删除远程分支 git push origin --delete <branch>、用 but status 验证工作区干净。
- 紧急恢复：but oplog 与 but undo 可恢复集成前状态；git checkout gitbutler/workspace 可脱离卡住状态。
使用方式
按集成前检查清单逐项确认后，选择上述任一工作流执行。CLI 工作流全程无需 GUI，会自动为堆叠分支设置正确的基础分支，并始终停留在 GitButler 工作区。直接合并工作流使用 --no-ff 保留分支历史。手动 PR 工作流适合需要走 GitHub 评审流程的情况。
适用场景
- 虚拟分支开发完成、测试通过、代码已评审，准备合并入 main。
- 需要清理已完成的虚拟分支。
- 需要处理堆叠分支的逐层合并。
- 需要从合并冲突、推送被拒或误操作中恢复。
限制与注意事项
必须遵守的规则：集成前必须创建快照（but oplog snapshot --message "..."）；使用 --no-ff 保留分支历史；git 操作后返回工作区（git checkout gitbutler/workspace）；集成前运行测试；堆叠分支自底向上完成。禁止：无快照备份就合并；跳过先更新 main（git pull）；忘记返回 gitbutler/workspace；在基础分支之前合并堆叠中间层；未经明确确认强制推送到 main。
相关技能：gitbutler-virtual-branches（核心 GitButler 工作流）、gitbutler-stacks（堆叠分支）。参考文件：gitbutler-virtual-branches/references/reference.md（CLI 参考与故障排查）。外部资源：GitButler GitHub Integration。