65 lines
2.9 KiB
Markdown
65 lines
2.9 KiB
Markdown
# 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 均已准确确认。
|
||
|
||
还要读取 `.craftkit/project.json` 的 `documents.workRoot`，检查该 Worktree 中与本分支任务对应的 `task.json` 和 ignored 文件。任务状态未到 `closed`、存在未登记的忽略文件或关闭清单尚未处理时，先执行 `knowledge:document-output close` 预览；用户要求保留现场时不得移除 Worktree。
|
||
|
||
展示检查结果、移除后保留的分支和唯一清理命令，取得用户确认后执行：
|
||
|
||
```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、直接删除目录或删除分支绕过占用保护。
|