分支切换与 Worktree：Git 并行开发指南
本篇涵盖的知识重点
- 分支从隐式变显式：新建任务页面会显示当前检出的分支，并可直接切换
- 普通文件夹（非 Git 仓库）下分支选择器置灰不可操作，正常 Git 仓库才可操作
- 切换分支时未提交改动有三种处理：Commit 到当前分支（默认）、Stash 变更、丢弃变更
- 选择远程分支会自动创建同名本地分支并跟踪它，切换失败时工作区完整回滚
- Worktree Task 为每个并行任务提供完全隔离的工作目录，同时与主仓库共享分支和 Git 对象
- Worktree 目录位于 ~/WorkBuddy/Worktrees，任务分支命名为 workbuddy/{基础分支}-{8位随机哈希}
- Base Branch 创建后锁定不可修改，任务分支在任务生命周期内不提供切换入口
- 自动清理：达到 25 个提示建议清理，达到 50 个需选择清理范围后才能继续创建
并行开发路径
分支切换与 Worktree 详解
作用以前要在终端或 IDE 里切分支，现在直接在工作空间内完成，连续作业不会被打断。
操作当工作空间内包含 Git 仓库时，新建任务页面会显示当前检出的本地分支名。点击分支选择器，可切换至其他本地分支或远程分支，并支持搜索。切换分支后点击发送初始任务指令时，会弹出确认对话框；未切换分支则无需确认，直接开始任务。
注意普通文件夹（非 Git 仓库）下分支选择器置灰不可操作，只有正常 Git 仓库才可操作。
- 普通文件夹（非 Git 仓库）：不可操作（置灰）——此时只能创建普通任务，看不到分支信息。
- 正常 Git 仓库：可操作——可查看当前检出分支并切换到其他本地或远程分支。
作用这一步直接决定你的改动是保住、暂存还是丢掉，选错代价很大。
操作切换分支时如果当前工作区存在未提交的改动，确认弹窗中会提供三种处理方式：Commit 到当前分支（默认）、Stash 变更、丢弃变更。选择远程分支时，系统会自动创建同名本地分支并跟踪该远程分支后再切换。
注意默认选中 Commit 这种最安全的方式；丢弃变更需二次确认，请谨慎使用。若切换失败，工作区会完整回滚到操作前的状态，不会残留中间态。若本地已存在同名分支，会提示你手动命名。
- Commit 到当前分支（默认）：弹出轻量提交面板，勾选变更文件并填写提交信息，提交完成后再切换到目标分支——改动想留在这条分支上时选它。
- Stash 变更：自动将当前改动（含未跟踪文件）暂存起来，再切换到目标分支——改动要带走、但还不想提交时选它。
- 丢弃变更：放弃所有未提交的改动后切换，需二次确认——确定这些改动不要了才选，请谨慎使用。
作用跑起来之后随时能确认自己在哪条分支上，能避免改错分支这类低级但代价高的问题。
操作在已有任务的对话界面中，工作区状态栏会实时显示当前检出的分支名，分支发生变化后会自动刷新，无需手动查询。
注意如发现分支名与预期不符，应停下来核对而不是继续下发改动指令。
作用多个任务同时推进时，文件系统层面的完全隔离能避免多个 Agent 的改动互相污染。
操作在新建任务页面输入任务指令，当工作空间包含 .git 目录时，输入框下方会展示 Worktree 开关（默认关闭）。开启后展开 Base Branch（基础分支）选择器，默认选中本地主分支（如 main），可切换为其他本地或远程分支，支持搜索与 fetch 刷新。发送任务指令后，系统开始创建 Worktree Task，界面会实时展示创建进度（大型项目可能需要数十秒到一分钟），创建完成后 Agent 自动启动并执行任务指令。
注意非 Git 项目（无 .git 目录）不展示 Worktree 开关，只能创建普通任务。Base Branch 在任务创建后锁定、不可修改；任务分支在任务生命周期内也不提供切换入口。创建时源工作区存在未提交改动不影响创建，新任务基于所选 Base Branch 的 HEAD commit 开始，不包含未提交改动。
作用并行任务多了容易混淆，靠标识才能一眼分清哪个是隔离任务、跑在哪条分支上。
操作Worktree Task 在任务列表和详情页中有明确标识：类型标识是任务列表标题前独特的 fork 类型图标，与普通任务明确区分（任务在列表中仍按原项目分组）；分支标识是任务卡片与任务标题旁展示的当前分支 Badge，例如 workbuddy/main-a3f8c2b1，为只读展示，hover 可查看详情，点击可复制分支名。创建时系统会在 ~/WorkBuddy/Worktrees 目录下创建独立的 worktree 工作目录。
注意创建失败时会自动回滚已创建的 worktree 与分支，不遗留半成品资源；不要手动删除 ~/WorkBuddy/Worktrees 下的目录，清理应使用系统提供的清理入口。
- 类型标识：任务列表标题前的 fork 图标，用于区分 Worktree Task 与普通任务；任务在列表中仍按原项目分组。
- 分支标识：任务卡片与标题旁的分支 Badge（如 workbuddy/main-a3f8c2b1），只读展示，hover 可查看详情，点击可复制分支名。
- 目录与命名：工作目录在 ~/WorkBuddy/Worktrees 下，任务分支命名格式为 workbuddy/{基础分支}-{8位随机哈希}，前缀 workbuddy/ 用于与你手动创建的分支区分。
作用并行任务会持续占用磁盘，同时有些能力当前版本并不支持，提前知道能少踩坑。
操作系统提供自动清理策略（仅针对 Worktree Task，创建普通任务不受任何限制）：达到 25 个时，在首页创建新 Worktree Task 会展示数量较多的提示，建议清理；达到 50 个时，勾选 Worktree 后会弹出「任务工作区已达上限」清理确认弹窗，需选择清理范围（清理超过 7 / 15 / 30 天前的任务工作区分支和文件），确认清理后才能继续创建，取消则阻塞创建。
注意轻量改动、单点查询使用普通任务即可，需要并行推进多个任务或隔离试验性方案时再开启 Worktree。当前版本（V1）暂不支持在云端 WorkBuddy 与 CodeBuddy 中使用 Worktree Task、非 Git 项目与跨多个仓库的 Worktree Task、从已有 Worktree Task fork 新任务，以及在任务内切换分支。
- 达到 25 个：创建新的 Worktree Task 时展示数量较多的提示，建议清理——这一步只是提醒，不阻塞创建。
- 达到 50 个：勾选 Worktree 后弹出「任务工作区已达上限」清理确认弹窗，需选择清理范围，确认后才能继续创建，取消则阻塞创建。
- 可选清理范围：清理超过 7 / 15 / 30 天前的任务工作区分支和文件。
- 适用范围：该策略仅针对 Worktree Task，创建普通任务不受任何限制。
使用建议与当前限制
- 使用建议：轻量改动、单点查询使用普通任务即可；需要并行推进多个任务或隔离试验性方案时再开启 Worktree。
- 切换分支时默认选中 Commit（最安全）；若切换失败，工作区会完整回滚到操作前的状态，不会残留中间态。
- 选择远程分支时系统会自动创建同名本地分支并跟踪该远程分支，若本地已存在同名分支会提示手动命名。
- 创建 Worktree Task 失败时会自动回滚已创建的 worktree 与分支，不遗留半成品资源。
- 当前版本（V1）暂不支持：云端 WorkBuddy 与 CodeBuddy 中使用；非 Git 项目与跨多个仓库；从已有 Worktree Task fork 新任务，以及任务内切换分支。
拓展训练
```markdown
我要在一个包含 Git 仓库的工作空间里新建 WorkBuddy 任务，并切换到另一条分支。请说明：新建任务页面在哪里显示当前分支、如何打开分支选择器、能否搜索、切换后发送初始指令时会发生什么、不切换分支时又会怎样。
然后重点说明：如果当前工作区有未提交的改动，弹窗会提供哪三种处理方式、默认是哪一种、各自的风险是什么；选择远程分支时系统会自动做什么；切换失败时工作区会变成什么状态。
最后告诉我普通文件夹（非 Git 仓库）下分支选择器是什么状态。
```能完成分支切换并发送任务；未提交改动按 Commit（默认）妥善处理；切换失败时工作区完整回滚到操作前状态，无中间态残留。
```markdown
我需要同时推进两个互不相关的任务：一个是新特性开发，一个是 bug 修复，希望它们的文件改动互不干扰。请说明在 WorkBuddy 里如何为它们分别开启 Worktree Task：开关在新建任务页的什么位置、默认状态是什么、Base Branch 怎么选、非 Git 项目为什么不显示这个开关。
另外请说明创建时系统会自动完成哪些动作（目录位置、分支命名规则、失败时如何处理），以及创建进度大概需要多久。
```两个任务各自在 ~/WorkBuddy/Worktrees 下的独立目录中运行，分支名形如 workbuddy/main-a3f8c2b1；两边的改动互不影响，创建失败时自动回滚无残留。
```markdown
我开了几个 Worktree Task 之后，在任务列表里分不清哪些是并行任务、各自跑在哪条分支上。请说明：任务列表标题前有什么类型图标、任务卡片和标题旁的分支 Badge 展示什么内容、这个 Badge 能不能点击或 hover、能否在任务内切换分支。
另外请说明 Base Branch 在任务创建后能否修改，以及任务列表是按什么分组的。
```能通过 fork 图标一眼认出 Worktree Task，通过分支 Badge 复制出分支名；明确知道 Base Branch 创建后锁定、任务内不提供分支切换入口。
```markdown
我的 Worktree Task 积累得比较多，担心占用磁盘。请说明系统的自动清理策略：达到 25 个时会发生什么、达到 50 个时会发生什么、可选哪些清理范围（7 / 15 / 30 天前）、取消清理会怎样、这套策略是否影响普通任务。
另外请列出当前版本（V1）暂不支持的四类能力，帮我判断哪些场景下我不该指望用 Worktree 解决。
```知道 25 个只是提示、50 个必须选择清理范围才能继续创建；清理策略只针对 Worktree Task；明确四类暂不支持场景（云端使用、非 Git 与跨仓库、从已有任务 fork、任务内切分支）。
```markdown
我在一个包含 Git 仓库的工作空间里新建 WorkBuddy 任务，需要切到另一条分支，但当前工作区还有未提交的改动。
请帮我梳理：①新建任务页面在哪里显示当前分支、如何打开分支选择器、是否支持搜索；②切换后发送初始指令时会发生什么、不切换时又会怎样；③确认弹窗提供的三种处理方式各自的适用时机与后果（请说明哪个是默认、哪个需要二次确认）；④如果切换失败会发生什么；⑤如果我选的是远程分支，系统会自动做什么，本地已有同名分支时又怎样。
请以「场景 → 该选哪种处理方式」的形式给出结论。
```能独立完成分支切换；未提交改动按 Commit（默认）妥善处理；知道切换失败会完整回滚、远程分支会自动创建同名本地分支并跟踪、同名冲突时会提示手动命名。
本文基于官方文档再创作，具体以官方文档站实际展示为准。