一、用途定位 本技能用于在 GitButler 中通过虚拟分支（virtual branches）实现并行开发：多个分支会同时应用到工作目录，编辑完成后再把文件归属到不同分支，无需反复 checkout。适用场景包括：同一工作区同时开发多个不相关的功能；多智能体在同一仓库并发开发；探索式编码（先写后整理）；需要对已有提交做事后重组；偏好可视化组织（GUI 与 CLI 结合）。资料明确不适合用于：使用 Graphite 的项目（模型不兼容）、简单的线性工作流（应使用普通 git）。
二、主要概念 虚拟分支：多个分支同时应用到工作目录。集成分支 gitbutler/workspace 用于跟踪虚拟分支状态，资料要求不要直接操作它。目标分支：所有工作从某个基线分支（例如 origin/main）分叉。文件分配：用 but rub 把文件变更块分配到分支。Oplog：操作日志，用于撤销与恢复，被称为安全网。
三、快速开始与核心循环 先执行 but setup 初始化仓库，然后用 but branch new feature-auth 创建分支。编辑文件后用 but status 查看变更与文件 ID，再用 but rub <file-id> <branch-name> 把文件分配到分支，最后用 but commit <branch> -m "message" 提交。核心循环为：创建分支、编辑、用 status 检查（获取文件 ID）、用 rub 分配、用 commit 提交，然后继续其他功能。资料强调与 git 的关键区别：所有分支同时可见，编辑后再把文件组织到分支，不需要 checkout。
四、but rub 的用途 资料称 but rub 是“瑞士军刀”，可通过组合不同实体完成多种操作：文件 ID 到分支表示把文件分配到分支；文件 ID 到提交表示用文件修订提交；提交 SHA 到分支表示在分支间移动提交；提交 SHA 到提交 SHA 表示压缩（较新并入较旧）。
五、常用命令 but setup 初始化；but status 查看变更与文件 ID；but branch new <name> 创建虚拟分支（加 --anchor <parent> 创建堆叠分支）；but rub <source> <target> 分配、移动、压缩或修订；but commit <branch> -m "msg" 提交；but commit <branch> -o -m "msg" 只提交已分配文件；but absorb 自动把未提交变更修订到合适的提交；but squash <commits> 压缩提交；but show <id> 查看提交或分支详情；but resolve <commit> 进入冲突解决模式；but push 推送分支；but pr new 创建或更新 PR；but config forge auth 通过 OAuth 认证 GitHub；but mark <branch> 自动把新变更分配到分支；but unmark 移除所有标记规则；but oplog 显示操作历史；but undo 撤销上一操作；but oplog snapshot --message "msg" 手动创建快照；but pull 用最新基线更新工作区；but gui 打开当前仓库的 GitButler GUI。任何命令都可加 --json 或 -j 获得 JSON 输出，例如 but status --json。
六、并行开发与冲突处理 资料给出的并行流程是：创建两个独立分支，在同一工作区分别编辑文件，用 but rub 分别分配，然后独立提交，两个分支同时存在且互不冲突。冲突处理方面，GitButler 在变基或更新时按提交逐个处理冲突，不同于 git 的全有或全无模型：变基会在部分提交冲突时继续；冲突提交会在 UI 或状态中标记；用 but resolve 进入按提交的解决模式；部分解决可保存稍后继续。典型步骤为：but pull 更新基线、but status 检查冲突、but resolve <commit-id> 进入解决、在编辑器中修复、but resolve status 检查剩余、but resolve finish 完成（或取消中止）。更详细的冲突处理流程见 references/reference.md#conflict-resolution。
七、自动分配与安全规范 可用 but mark auth-feature 为某分支设置自动分配规则，用 but unmark 清除全部规则，适合多智能体工作流中把变更路由到指定分支。资料要求始终在虚拟分支内使用 but，只在把完成的工作整合进 main 时使用 git；git 操作后回到 gitbutler/workspace（git checkout gitbutler/workspace）；高风险操作前用 but oplog snapshot 创建快照；创建后立即分配文件；使用 but rub 前先用 but status 获取文件 ID。同时明确禁止：在虚拟分支上使用 git commit（会破坏 GitButler 状态）；使用 git add（GitButler 管理索引）；在虚拟分支上使用 git checkout（无需 checkout）；把 gitbutler/integration 推送到远程（它仅在本地）；在同一仓库混用 Graphite 与 GitButler；直接把 but status 管道输出（会导致 panic），应先捕获输出再处理。
八、故障排查与恢复 常见症状与解决：文件无法提交时先分配；管道 panic 时先捕获输出；混用 git 与 but 破坏状态时用 but pull 或 but setup；工作丢失时用 but undo 或 but oplog restore <snapshot-id>。恢复方式包括：but undo 快速撤销、but oplog restore <snapshot-id> 完整恢复、but oplog 查看历史。更详细排查见 references/reference.md#troubleshooting-guide，恢复场景见 references/reference.md#recovery-scenarios。
九、参考资料 references/reference.md 提供完整 CLI 参考、JSON 模式与故障排查；references/examples.md 提供真实工作流示例；references/ai-integration.md 介绍钩子、MCP 服务器与智能体生命周期。相关资料还包括 gitbutler-multi-agent、gitbutler-stacks、gitbutler-complete-branch 等技能，以及 GitButler 官方文档和 AI 集成说明。
十、限制说明 关于本技能的收费、价格、具体支持平台、与更多工具的兼容性等资料暂未提供。