Worktree 分支规则

创建条件

满足任一条件时，优先在独立 worktree 创建新需求、缺陷或维护分支，不切换当前主工作区：

主工作区存在未提交文件、本地配置、环境配置或缓存；
用户要求不影响当前 checkout；
当前分支正被 IDE、服务或测试占用；
当前工作需要与主工作区并行进行。

Worktree 共享仓库对象和本地分支引用。同一个本地分支不能同时被两个 worktree 签出。

创建前检查

确认主仓库绝对路径、目标 worktree 绝对路径、分支名、基准引用和完整哈希。检查目标路径不存在、同名本地及远程引用的处理已经确认、目标分支未被其他 worktree 占用。分支名可能包含中文时始终加引号。

取得分支创建授权后执行唯一命令：

git worktree add -b "<branch>" "<absolute-worktree-path>" "<base>"

创建后验证新 worktree 的分支、HEAD 和状态，并重新检查主工作区分支、HEAD 和未提交内容未变化。报告该分支的占用路径，提示主工作区不能同时签出，并记录任务完成后的清理义务。

关闭条件

创建分支的当次操作完成不等于 worktree 生命周期结束。只有分支开发任务、验证和用户要求的交付已经完成，并且用户不再要求保留现场时，才进入 close。

关闭前必须满足：

worktree 没有未提交或未跟踪文件；
没有进行中的 merge、rebase、cherry-pick 或 revert；
当前 HEAD 已被预期本地分支引用；
主仓库、worktree 路径、分支和 HEAD 均已准确确认。

还要读取 .craftkit/project.json 的 documents.workRoot，检查该 Worktree 中与本分支任务对应的 task.json 和 ignored 文件。任务状态未到 closed、存在未登记的忽略文件或关闭清单尚未处理时，先执行 knowledge:document-output close 预览；用户要求保留现场时不得移除 Worktree。

展示检查结果、移除后保留的分支和唯一清理命令，取得用户确认后执行：

git -C "<main-repository>" worktree remove "<absolute-worktree-path>"

不得直接删除目录，不得默认使用 --force，不得删除或重置分支，也不得批量清理其他 worktree。

关闭后验证

Test-Path -LiteralPath "<absolute-worktree-path>"
git -C "<main-repository>" rev-parse --verify "<branch>"
git -C "<main-repository>" worktree list --porcelain
git -C "<main-repository>" status --short --branch

目录不存在、占用记录已释放、分支和提交仍存在、主工作区原有状态未变化时，关闭才算完成。

分支占用错误

fatal: '<branch>' is already used by worktree at '<path>'

该错误表示分支仍由指定 worktree 签出。若任务仍在进行，继续在该 worktree 中操作；若任务已经结束，执行 close。不得强制 checkout、直接删除目录或删除分支绕过占用保护。

2.9 KiB Raw Blame History Unescape Escape