git-worktrees

使用 Git Worktrees

确保工作发生在隔离工作区。优先用平台原生 worktree 工具，没有再退回手动 git worktree。

核心顺序：先探测已有隔离 → 用原生工具 → 退回 git → 别和 harness 较劲。

步骤 0：先探测是否已隔离

建任何东西之前，先确认你是不是已经在隔离工作区里。

GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
# submodule 也会让两者不等，先排除
git rev-parse --show-superproject-working-tree 2>/dev/null

• GIT_DIR != GIT_COMMON 且非 submodule → 已在 worktree 里，别再建，直接去步骤 2。
• 相等（或在 submodule）→ 普通检出。用户没预先表态过偏好的话，先问："要不要建隔离 worktree？保护当前分支不被改动。" 用户拒绝就原地干，跳步骤 2。

步骤 1：建隔离工作区

1a. 原生工具优先 — 有没有 EnterWorktree / WorktreeCreate / /worktree 命令 / --worktree 标志之类的？有就用它，跳步骤 2。原生工具自动处理目录、建分支、清理。有原生工具还手敲 git worktree add 会制造 harness 看不见的幽灵状态。

1b. git 退路（仅当无原生工具）

目录选择优先级：用户声明的偏好 > 已存在的 .worktrees/（优先）或 worktrees/ > 默认 .worktrees/。

项目内隔离目录必须先确认被 ignore；原生工具爱建哪建哪，但只要落在项目内，就提示用户把对应目录加进 .gitignore：

git check-ignore -q .worktrees 2>/dev/null || echo "未 ignore：先加进 .gitignore 并 commit"
# 如果原生工具建在 .claude/worktrees/，同理确认 .claude/worktrees/ 被 ignore

建：

git worktree add ".worktrees/$BRANCH" -b "$BRANCH"
cd ".worktrees/$BRANCH"

权限错误（沙箱拦截）→ 告诉用户沙箱挡了 worktree 创建，改为原地工作，原地跑 setup 和基线测试。

步骤 1.5：锚定工作区路径（最易致命的坑）

AI 在 worktree 里最常犯、代价最大的错：建了 worktree，后续却用主仓路径干活——Read/Write/Edit 用了主仓的绝对路径（记忆里的老路径），或 cd 回了主仓。结果所有改动落进主仓的当前分支，你新建的 worktree 分支空空如也，主仓还被意外污染。等到"工作树干净、文件却不见"才发现，已经绕了很久。

建完/进入 worktree 后，立刻锚定它的绝对路径，之后一切操作以它为根：

WT=$(git rev-parse --show-toplevel)   # 当前 worktree 根，记住它
git worktree list                     # 看清每个目录对应哪个分支
echo "已锚定工作区：$WT"

铁律：

• 所有文件操作用以 $WT/ 开头的路径。每次 Write/Edit 前确认目标路径在 worktree 里，别用记忆里的主仓路径（如 …/Desktop/<repo>/…）。
• 绝不 cd 回主仓。需要主仓信息用 git -C <主仓路径> …，不切目录。
• 工具默认工作目录可能仍是主仓——靠绝对路径锚定，不靠"当前目录"。

步骤 1.6：钉死在隔离分支（第二条致命铁律）

路径锚定只防"文件落错仓"；还有一类同样致命的错位是分支 checkout 错位。

心智模型：分支是仓库级单例。 master / main 这类分支同一时刻只能被一个工作区 checkout——你在 worktree 里 git checkout master，就把主干的唯一 checkout 位挪进了这个临时目录，主仓和所有其他会话立刻切不到 master，直到你归还。干完不归还，主干就被这个临时 worktree 占死。

铁律：

• worktree 内绝不 git checkout / git switch 到 master / main 等共享主干。 这个 worktree 自始至终待在自己的隔离分支上。
• 要把活合进主干，别在 worktree 内切主干来 merge，改用下列之一：① 走 PR 回流；② 在主仓执行 git -C "<主仓路径>" merge "$BRANCH"（让 merge 发生在主仓，当前 worktree 不切分支）。
• 万不得已在 worktree 内切过主干，merge 完第一时间 git checkout - 切回隔离分支归还，绝不停在主干上（见步骤 4c）。

步骤 2：项目 setup

自动探测并装依赖（有哪个装哪个）：package.json→装包（按 lockfile 选包管理器：pnpm-lock.yaml→pnpm / yarn.lock→yarn / package-lock.json→npm / bun.lock / bun.lockb→bun） / Cargo.toml→build / requirements.txt/pyproject.toml→装 / go.mod→download / pom.xml→依赖解析 等。

步骤 3：验证干净基线

跑项目对应的测试命令。失败 → 报告并问是否继续（区分新 bug 和既有问题）。通过 → 报告就绪。

步骤 4：回流前检查

worktree 只提供隔离，不决定合并拓扑；但回流应优先让工作分支按项目约定正常合并。别为了省事把 diff/apply、复制文件、cherry-pick 当默认回流方式——这会绕过分支语义，让 worktree 分支变成废分支。

4a：确认目标 base

优先用 PR base / 用户指定目标 / 项目默认分支，不要硬编码 main：

BASE_REF="<目标主干或 PR base>"
git -C "$WT" fetch --all --prune
git -C "$WT" diff --name-only "$BASE_REF"...HEAD

4b：扫"非文本语义冲突"（git 不会替你发现）

git 只发现同一区块文本冲突；两条分支各占一个"下一个号"时，文件不同也可能合坏。上一步 diff 出现这些资源就核对：

• Flyway / Liquibase 迁移序号
• protobuf field number
• 枚举存储值 / ordinal / 数据库列序
• 错误码 / 消息号 / 路由表 / 唯一注册表

发现冲突就改本分支（迁移序号、字段号、错误码等），别留到主干 merge 时凑合。

4c：正常回流，再清理

优先把 $BRANCH 按项目 / 平台约定回流（PR merge / git merge；具体 merge commit、squash merge、rebase merge 听项目约定）。只有用户明确要求挑提交 / 补丁提取，或分支无法合并且说明原因时，才用 cherry-pick / patch。

别在 worktree 内 checkout 主干来 merge（步骤 1.6）——要本地合就 git -C "<主仓路径>" merge "$BRANCH"，让 merge 发生在主仓、当前 worktree 不切分支。万一已经在 worktree 内切到主干合过，先 git checkout - 归还隔离分支再往下清理；停在主干上不归还 = 主干被这个临时目录占死，主仓和其他会话都切不过去。

回流后清理 worktree。原生工具创建的优先用原生清理；手动 git worktree 用已锚定路径：

git -C "<主仓路径>" worktree remove "$WT"
git -C "<主仓路径>" branch -d "$BRANCH"   # 仅真实 merge 后可靠；squash/rebase 回流后按项目约定删分支

困惑时：查地面真相，别猜

出现"改了文件却找不到 / git status 干净但改动没了 / 新建的分支是空的" → 几乎一定是改动落错了目录。别猜，直接对比两个工作区各自的真相：

git worktree list                       # 每个目录 + 它的分支 + HEAD，一眼看清谁是谁
git -C "$WT" status --short             # worktree 的改动
git -C "<主仓路径>" status --short      # 主仓的改动
ls "$WT/<你以为改过的文件>" 2>/dev/null || echo "worktree 里没有这个文件"

改动出现在主仓而非 $WT = 路径根用错了。停手，把改动迁到 worktree 重做，别在主仓继续叠。撞到第二次困惑就立刻查这个，别再猜第三次。

完成时同样验证：提交前确认改动在 worktree 分支可见、主仓 status 干净。

常见错误

• 改动落错仓：建了 worktree 却用主仓绝对路径 Read/Write/Edit，或 cd 回主仓 → 改动落主仓当前分支、worktree 分支空、主仓被污染。→ 建完锚定 $WT，所有路径以它为根，绝不 cd 回主仓（步骤 1.5）。
• 分支 checkout 错位：在 worktree 内 git checkout master/main 做 merge 或图省事 → 主干的唯一 checkout 位被挪进临时 worktree，主仓和其他会话全切不到主干，干完不归还就一直卡死。→ worktree 钉死隔离分支，要合主干去主仓 git -C "<主仓>" merge，切过务必 git checkout - 归还（步骤 1.6 / 4c）。
• 和 harness 较劲：有原生隔离还手建 worktree。→ 步骤 0/1a 先探测、先用原生。
• 跳过探测：在已有 worktree 里又套一个。→ 永远先跑步骤 0。
• 跳过 ignore 校验：worktree 内容被 git 跟踪污染状态。→ 项目内目录先 git check-ignore。
• 带着失败的基线往下做：分不清新旧 bug。→ 先报告，拿到明确许可再继续。
• 用补丁提取绕过分支：AI 容易把 worktree 改动 diff/apply 到主仓，或 cherry-pick 单个提交。→ 优先让 $BRANCH 正常回流；合并形态按项目约定，不明确就问（步骤 4c）。
• 硬编码 base/路径：main...HEAD 或 .worktrees/$BRANCH 会扫错 / 删错。→ 用 $BASE_REF、$WT 和 git -C "<主仓路径>"（步骤 4a/4c）。
• 撞号但 git 不报：两条分支各占同一个 Flyway 序号 / proto tag / 错误码等 → git 不报冲突，合进去行为错乱。→ 合并前扫非文本语义冲突，本分支改号（步骤 4b）。