Back to Details

worktree-create

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Worktree Create

创建Git Worktree

Stand up any number of isolated git worktrees from a list of branches — each created off the right base, given its gitignored config, its dependencies, and a health check — by fanning out one setup subagent per worktree so they run in parallel. The per-worktree work is app-agnostic and detected from the repo, never hardcoded.
从分支列表中创建任意数量的独立git worktree——每个worktree都基于正确的基础分支创建，会配置被git忽略的文件、安装依赖并执行健康检查——通过为每个worktree分配一个设置子代理（subagent）来实现并行运行。每个worktree的配置过程与应用无关，完全从仓库自动检测，而非硬编码。

Input

输入参数

$ARGUMENTS
is the list of branches to create.
  • None given → ask which branches to create (or offer to derive them from the tickets in play). Don't guess.
  • One → set up a single worktree inline (a fan-out of one is unnecessary).
  • Two or more → fan out one subagent per branch, in parallel.
$ARGUMENTS
是要创建的分支列表。
  • 未提供参数 → 询问用户要创建哪些分支（或提议根据当前处理的工单生成分支）。请勿自行猜测。
  • 单个分支 → 直接创建单个worktree（无需分配子代理）。
  • 两个及以上分支 → 为每个分支分配一个子代理，并行执行创建操作。

Detect the project setup ONCE, before fanning out

在分配子代理前，先一次性检测项目配置

Read 
references/worktree-setup.md
— it is the general checklist of everything a fresh worktree needs plus how to detect each piece. Determine from this repo (not from assumptions), one time:
  • the install command(s) (monorepo → one per package),
  • the gitignored env/config files to copy (or the repo's 
    .worktreeinclude
    ),
  • the verification/health-check command (a health endpoint if the app exposes one, else a build/test smoke — prefer whatever CI runs),
  • a base port, only if the health check starts a service.
Pick a worktree root (
worktrees/<branch>
, gitignored) and, if services get started, assign each worktree a distinct port = 
base + index
so parallel servers don't collide.
阅读 
references/worktree-setup.md
文件——这是一份通用检查清单，包含新worktree所需的所有配置项及检测方法。仅从当前仓库（而非预设规则）一次性确定以下内容：
  • 安装命令（如果是monorepo，则每个包对应一个安装命令），
  • 需要复制的被git忽略的环境/配置文件（或仓库中的 
    .worktreeinclude
    文件指定的内容），
  • 验证/健康检查命令（如果应用暴露了健康检查端点则使用该端点，否则执行构建/测试冒烟检查——优先采用CI流程中使用的检查方式），
  • 基础端口（仅当健康检查需要启动服务时才需确定）。
选择worktree根目录（
worktrees/<branch>
，该目录已被git忽略），如果需要启动服务，则为每个worktree分配唯一端口，计算公式为 
基础端口 + 索引值
，避免并行运行的服务器端口冲突。

Fan out one setup subagent per branch (parallel)

为每个分支分配一个设置子代理（并行执行）

Spawn all subagents at once with the Task tool. Give every subagent the same prompt, substituting only 
BRANCH
and 
PORT
:
Set up a git worktree for branch: BRANCH   (assigned port: PORT, only relevant if you start a service)

Follow the checklist in .claude/skills/worktree-create/references/worktree-setup.md. Concretely:
1. Create the worktree off the base branch:  git worktree add worktrees/BRANCH -b BRANCH
2. Copy the gitignored config/secrets the project needs into worktrees/BRANCH
   (the env/config files detected for this repo; verify each with `git check-ignore` before copying).
3. Install dependencies with the project's detected package manager (every package, for a monorepo).
4. Run any generate/build step the app needs to boot (skip if none).
5. Verify: run the detected health check (start + hit the health endpoint on PORT if there is one,
   else a build/typecheck/test smoke). Then stop any server you started.

Report exactly: worktree path · branch · deps installed (yes/no) · health check (PASS/FAIL) · any errors.
Fill the detected commands (install, env-file list, health check) into the template. For a single branch, run the steps directly instead of spawning.
使用Task工具一次性启动所有子代理。为每个子代理提供相同的提示，仅替换其中的
BRANCH
和
PORT
参数：
为分支创建git worktree：BRANCH   （分配端口：PORT，仅在启动服务时生效）

遵循.claude/skills/worktree-create/references/worktree-setup.md中的检查清单。具体步骤：
1. 基于基础分支创建worktree：git worktree add worktrees/BRANCH -b BRANCH
2. 将项目所需的被git忽略的配置/密钥文件复制到worktrees/BRANCH目录
   （复制前需使用`git check-ignore`验证每个文件是否确实被git忽略）。
3. 使用项目检测到的包管理器安装依赖（如果是monorepo，则需为每个包安装依赖）。
4. 执行应用启动所需的生成/构建步骤（如果没有则跳过）。
5. 验证：执行检测到的健康检查（如果有健康端点，则启动服务并访问PORT端口的健康端点；否则执行构建/类型检查/测试冒烟检查）。然后停止所有启动的服务器。

需准确报告：worktree路径 · 分支 · 依赖是否安装完成（是/否） · 健康检查结果（通过/失败） · 任何错误信息。
将检测到的命令（安装命令、环境文件列表、健康检查命令）填入上述模板。如果是单个分支，则直接执行上述步骤，无需启动子代理。

Aggregate and report

汇总并报告结果

Collect the reports and print a per-worktree summary (path · branch · deps · health · port), a combined 
N worktree(s) ready
line, the next step (open each worktree / start a PIV loop in it), and the cleanup reminder: 
git worktree remove worktrees/<branch>
once a branch is merged.
If any worktree failed its health check, surface it clearly and do not report it ready.
收集所有子代理的报告，打印每个worktree的摘要（路径 · 分支 · 依赖状态 · 健康检查结果 · 端口），汇总显示
N个worktree已准备就绪
，给出下一步操作建议（打开每个worktree / 在其中启动PIV循环），并提醒清理事项：分支合并后执行
git worktree remove worktrees/<branch>
命令删除对应的worktree。
如果任何worktree的健康检查失败，需明确指出，且不要将其标记为已就绪。

Resources

参考资源

  • references/worktree-setup.md
    — the general, app-agnostic checklist of everything a fresh worktree needs, and how to detect each piece per project. Read it before detecting the setup.
  • references/worktree-setup.md
    — 通用的、与应用无关的检查清单，包含新worktree所需的所有配置项，以及针对不同项目的检测方法。请在检测项目配置前阅读此文件。