# Worktree 分支规则

## 创建条件

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

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

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

## 创建前检查

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

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

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

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

## 关闭条件

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

关闭前必须满足：

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

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

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

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

## 关闭后验证

```text
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
```

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

## 分支占用错误

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

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