git-worktree

Git worktree 管理器

门槛：如果任务在现有 worktree 中运行（已给出 worktree 路径，且未请求创建、移除或切换），则不适用任何创建流程：直接在该 worktree 中操作，并跳过此技能。 检查方法：git worktree list 中会将 git rev-parse --show-toplevel 的结果列为链接。

工作规则

• 保留其他会话的分支、文件和已暂存的工作（参见“所有权”）。
• 验证依赖项会从预期的 worktree 中解析第一方代码。
• 在用户授权范围内执行合并、推送和清理；报告实际操作的确切检出及生成的提交。

始终使用管理器脚本

切勿直接调用 git worktree add；始终使用 worktree-manager.sh 脚本。

管理器负责设置：

1. 从主检出复制 .env、.env.local、.env.test 等文件，但仅当基线是默认分支或已包含已获取提交的本地分支时才会复制（仅存在于 origin 的分支不会复制）；绝不会覆盖新 worktree 中已有的文件或符号链接，也不会跟随它们
2. 确保主检出中的 .gitignore 包含 .worktrees
3. 创建一致的目录结构
4. 创建完成后，如果检测到依赖项，则安装依赖：package.json → npm install、composer.json → composer install、pyproject.toml → pip install -e .、go.mod → go mod download

不受信任的基线（PR 分支、fork 或仅存在于 origin 的分支、第三方代码）： 使用 --no-env 创建，绝不将 copy-env 复制到 worktree 中，并确保命令不包含凭据。跳过安装；如有需要，禁用生命周期脚本和插件（npm ci --ignore-scripts、composer install --no-scripts --no-plugins），并且绝不运行 pip install -e .，因为这会运行构建后端。

所有命令均使用：bash ${CLAUDE_PLUGIN_ROOT}/skills/ia-git-worktree/scripts/worktree-manager.sh <command>。如果 CLAUDE_PLUGIN_ROOT 未设置（非 Claude Code 的运行环境），请相对于此技能自身的目录解析脚本路径。

创建 worktree 之前，先导出唯一的 WORKTREE_SESSION_ID，并在本会话后续调用管理器时继续使用同一个值。例如：export WORKTREE_SESSION_ID="$(python3 -I -c 'import uuid; print(uuid.uuid4())')"。管理器会在每个新 worktree 的 Git 元数据中记录所有权。未设置会话 ID 也能创建，但管理器会拒绝清理此类 worktree；绝不要借用之前会话的 ID 来绕过所有权检查。

管理器脚本会从 origin 获取 <base> 到调用专用的引用中，解析该提交，并基于其 SHA 创建分支，即使 origin/<base> 不存在或已过时，或其他检出正在并发获取内容时也一样。它只会移除自己的专用引用，绝不会在调用方的工作树中检出 <base>。如果获取失败（离线、无远程），则改为解析本地 <base>。PR 审查：将已获取的 PR 分支作为 <base> 传入，然后验证其 SHA（workflow-examples.md）。详情请参阅：troubleshooting.md。

命令

命令	说明	示例
create [--no-env] <branch> [from]	创建工作树和分支（默认基于 main）	...worktree-manager.sh create feature-login
list / ls	列出所有工作树及其状态	...worktree-manager.sh list
switch <name> / go	输出已注册工作树的绝对路径；调用方将其用作工作目录	target=$(...worktree-manager.sh switch feature-login)
copy-env <name>	将 .env 文件复制到现有工作树	...worktree-manager.sh copy-env feature-login
cleanup <name> [...] / clean	确认移除指定的、由当前会话拥有且干净的工作树	...worktree-manager.sh cleanup feature-login

使用 env -C "$target" <command> 或运行器的工作目录参数执行命令。子脚本无法更改调用方的工作目录。从任何主检出或链接检出（包括子目录）都可以列出工作树并解析名称。

清理操作会拒绝当前检出、其他会话的工作树，以及包含已跟踪、未跟踪或已忽略文件的工作树。因此，自动复制的 .env 文件和已安装的依赖项，必须先由用户明确处理，才能清理。请确认没有进程正在使用指定工作树；管理器无法检测到所有外部读取者。Git 的常规移除保护仍保持启用，包括拒绝移除已锁定的工作树。不要强制删除或抑制错误来完成清理。

安全验证

在主检出中创建工作树之前，确认 .worktrees 已被忽略：

# Verify .worktrees is ignored (should output ".worktrees")
git check-ignore .worktrees || echo "WARNING: .worktrees not in .gitignore"

如果未被忽略，请先将其添加到 .gitignore，再继续。

运行任何基线测试套件或迁移之前，先应用 ia-verification-before-completion 的有效目标预检。解析工作树的环境/配置覆盖项；验证一次性数据库和服务目标，切勿使用开发数据库。复制的 .env 文件不能证明环境已隔离。如果未验证一次性目标，请在测试前停止。然后运行测试套件或其最快的相关子集，以在实施前建立干净的基线。

所有权

• 每个工作树只允许一位编写者。将所有并非在当前会话中创建的 git worktree list 条目视为只读；上一轮留下的工作树也不属于当前会话。最容易让人想要复用的，恰恰也是最危险的：现有工作树已经配置好了依赖和环境，另一个会话可能正在其中运行测试套件。
• 当前会话正在某个工作树中运行测试套件时，不要修改该工作树。测试运行器会在运行过程中逐步加载源文件，因此中途编辑会导致大量失败，看起来与真正的回归完全一样。
• 与某项声明相矛盾的一连串失败，只能作为测试框架的假设，不能当作结论。在一个刚刚确认干净的工作树（git status --short 为空）上重新运行并返回结果之前，不要记录或报告归咎于自身造成问题的结论。
• 必须进行修改时，应确认恢复成功（将令牌的数量与原始数量进行比对，并运行 git status --short），而不是盲信 git checkout --。
• 一个检出只有一个索引：直接提交会包含无关的暂存条目，而 git commit -- <paths> 会记录完整的工作树文件，包括调用者或协作者的修改块。只有确认所选每项更改的整个文件均由你负责时，才使用路径规格提交。对于混合修改块，应在由当前会话独占的干净检出中提交可归属的补丁，同时保留调用者的 HEAD、索引和文件。检查拟议补丁和已提交补丁的具体内容，而不只是文件名或 --stat；遵循 commit-ownership.md。
• 在 git -C 推送中绝不要使用 HEAD:。应在已编辑的工作树中解析 SHA，明确推送该 SHA，并使用 git ls-remote 确认；租约无法阻止选中另一个检出的 HEAD。详情见：commit-ownership.md。
• 处理红绿测试时绝不要运行 git stash：关联的工作树共用同一个 stash 栈。请使用 commit-ownership.md 中的补丁文件循环和 stash 恢复方法。
• 根据引用（rev-parse <branch>）回答分支问题，而不要依赖工作树的 HEAD，因为其他会话可能会移动它；参见 commit-ownership.md。

每条命令都使用 env -C <worktree> <cmd>，绝不要使用 cd。Shell 的当前工作目录会在调用之间保留，因此，哪怕只是出于无关原因运行一次 cd <repo-root>，也会悄悄改变后续所有命令的位置：探测文件会被写入共享的主工作树，并针对其中的文件内容运行，而整理时习惯性执行的 git checkout -- <path> 也会变成对错误工作树的写入。使用 git -C 的习惯无法推广到其他命令：解释器、测试运行器、代码检查工具和 cat > heredoc 都会使用当前工作目录。让任何探测命令都打印它所运行的工作树。

验证

• git worktree list 显示新条目
• .worktrees 已被忽略，或位于裸仓库的公共目录中
• 工作树中已安装依赖（可信基线；不可信基线遵循上述规则）
• 工作树中的基线测试套件通过

参考资料

• workflow-examples.md - 代码审查和并行开发工作流
• troubleshooting.md - 常见问题、新远程基线行为、目录结构及工作原理
• hooks-and-excludes.md - Husky 下的钩子安全性、.git/info/exclude 与 .gitignore
• commit-ownership.md - 整文件提交和混合修改块的隔离暂存
• worktree-manager.sh - 管理脚本

特定任务参考资料

在实现或审查相应行为之前，请阅读相关参考资料：

• 对于依赖来源、环境适配、审查/工作流、分支完成或钩子：请参阅 worktree-integration.md。

适用相应主题时，可查阅现有的专门参考资料：