git-worktree

用于并行 Agent 的 Git Worktree

在 Cloudroom 中（已设置 $ROOM_THREAD_ID）

切勿自行运行 git worktree add。Cloudroom 只会删除它创建的 worktree，因此手动创建的 worktree 会永远堆在 ~/code 中。

• **新任务：**改为使用 New worktree 启动线程。

• **将此线程移至独立的 worktree：**将其分叉到由 Cloudroom 管理的 worktree。Cloudroom 会创建分支，并在最后一个线程归档后删除文件夹（在 worktree 保留期限之后，默认为 30 天）。

  room-cli thread fork "$ROOM_THREAD_ID" --new-environment worktree --title "<task>" \
    --prompt "You now run in a new worktree. Copy the gitignored .env files from <primary checkout> into it, then stop and wait for the user."
  

  它会从 main 分支，因此未提交的修改会留在原处；请先提交这些修改，或传入 --base-branch <ref>。然后告知用户在新线程中继续，并归档此线程。跳过本技能的其余部分。

从这里开始

编辑前先确认你所在的位置：

[ "$(git rev-parse --path-format=absolute --git-dir)" = "$(git rev-parse --path-format=absolute --git-common-dir)" ] \
  && echo "primary checkout" || echo "worktree"

• 主检出目录 → 创建一个以任务命名的 worktree，完成下方的设置，然后在编辑前 cd 进入其中。
• Worktree（包括由 Cursor 创建的 worktree）→ 继续执行任务。

工作模式

Worktree 拥有各自独立的工作文件和分支，但共享 Git 历史记录、stash、配置和引用。

• **一个任务 = 一个 worktree = 一个 Agent 会话。**绝不让多个 Agent 共用同一个工作目录。
• 主检出目录应保持在 main，仅用于审查、合并和推送。
• 不会自动合并。合并或丢弃 worktree 前，必须由人工审查每个差异。
• 任务分支应保留在本地，并尽量缩短其生命周期。除非用户明确要求推送任务分支，否则只推送 main。
• 一次只合并一个 worktree。如果 main 有更新，请先将任务分支变基，然后再合并。

创建和移除

git worktree add ../myrepo-task-x          # new worktree + branch "myrepo-task-x"
git worktree add ../fix-y -b fix-y main    # explicit branch off main
git worktree list                          # see all worktrees
git worktree remove ../myrepo-task-x       # delete when merged/abandoned
git worktree prune                         # clean up stale registrations

一个分支只能在一个 worktree 中检出，main 也不例外。

在 Cursor 中，使用 Agents Window 或 /worktree <task>。/apply-worktree 会将结果应用到主检出目录；/delete-worktree 会丢弃结果。/best-of-n model1,model2 <task> 会在并行 worktree 中按每个模型运行相同任务。Cursor 会自动删除较旧的 worktree，因此请及时保存结果；推送任务分支仍需获得明确批准。

完成设置

新建的 worktree 只包含受跟踪的文件。开始任务前，请先完成初始化：

1. 环境/密钥文件 — 从主检出目录复制 .env、.env.local 等类似文件。切勿创建符号链接，否则编辑会修改原文件。
2. 依赖项 — 在本地安装（npm ci、pnpm install、uv sync、bundle install）。切勿将主检出目录中的 node_modules 创建为符号链接：Next.js/Turbopack 等打包工具会拒绝 worktree 以外的路径。如果它是符号链接，请使用 rm -f node_modules 将其移除，然后正常安装。
3. 数据库和服务 — 选择共享状态或每个 worktree 独立状态。对于共享服务，请固定其标识，以避免实例重复和端口冲突。对于共享的 Docker Compose 服务，请固定项目名称，例如设置顶层 name:；否则，每个 worktree 的文件夹名都会创建一个独立项目。复制或重新初始化每个 worktree 独有的状态，例如 SQLite 文件。
4. 端口 — 每次只运行一个开发/测试服务器和调试器，或为每个 worktree 配置独立端口。
5. 生成文件和缓存 — 在 worktree 中重新生成被 Git 忽略的输出（npm run build、代码生成）。
6. Git 钩子 — core.hooksPath 和 .git/config 是共享的；请确认钩子脚本不会假定路径是主检出目录的路径。

自动化设置

在 Cursor 中，.cursor/worktrees.json 会在创建 worktree 时运行设置流程（$ROOT_WORKTREE_PATH 是主检出目录）：

{
  "setup-worktree": [
    "npm ci",
    "cp $ROOT_WORKTREE_PATH/.env.local .env.local"
  ]
}

否则，请将检查清单放入 scripts/setup-worktree.sh，并在每个新 worktree 中先运行该脚本。从 worktree 中查找主检出目录的方式如下：

dirname "$(git rev-parse --path-format=absolute --git-common-dir)"

合并和清理

# from the primary checkout, after reviewing the worktree's diff:
git merge --no-ff task-branch     # or: git merge --squash task-branch
git worktree remove ../myrepo-task-x
git branch -d task-branch

在 Cursor 中，使用 /apply-worktree，然后审查并提交。

• 分支合并或推送到 main 后，立即删除对应的 worktree。没有其他机制会清理它们。
• 对停滞数天的 worktree 进行变基或重新启动。
• 尽早且频繁地提交。删除 worktree 会丢失未提交的工作；提交则会保留在共享仓库中。