using-git-worktrees

使用 Git Worktree

概述

Git worktree 会创建共享同一仓库的隔离工作区，让你无需切换分支即可同时处理多个分支。

**核心原则：**在 opencode v2 中，使用原生的 worktree_* 工具创建 worktree，移动的是 会话，而不只是 shell。这样 opencode 的跟踪（列表/移除）、项目配置和 AGENTS.md 发现都会指向正确的位置。

开始时请说明：“我将使用 using-git-worktrees 技能来设置隔离工作区。”

默认路径：原生 Worktree 工具

在 opencode v2 中运行时（通常情况）使用此路径。这些工具包括 worktree_create、worktree_list、worktree_remove（Code Mode 命名空间 opencode），以及 session_move。

1. 创建 worktree

调用 worktree_create 并传入 name — 使用功能/分支名称（例如 auth、fix-login-timeout）。它会返回 { directory }。

worktree 的存放位置由项目的 opencode 配置中的 worktree.directory 设置决定，而不是由该技能决定：

• **未设置（默认）：**opencode 的数据目录 worktree/<project-id prefix>/<name> — 位于仓库之外，因此无需添加到 gitignore。
• 已设置（例如 "worktree": { "directory": ".worktrees" }）：相对路径会基于项目的规范检出目录解析。如果目录位于仓库 内部，则必须将其加入 gitignore（见下文）。

不要通过 git worktree add 手动指定位置 — opencode 只会记录并管理由自身创建的 worktree，因此手动创建的 worktree 无法通过 worktree_list / worktree_remove 看到。

如果用户希望使用非默认位置，符合 v2 惯例的做法是在配置中设置 worktree.directory（并在 AGENTS.md 或记忆中注明），而不是为每个会话单独选择路径。

2. 创建分支

worktree_create 不接受分支名称：新 worktree 会基于仓库当前提交处于分离 HEAD 状态。在 worktree 内创建分支：

git checkout -b "<branch-name>"

（git checkout main 会失败 — 因为 main 已在主 worktree 中检出，这是预期行为，并非错误。）

3. 将会话移入 worktree

调用 session_move，并将 worktree 目录作为 directory 传入。移动会在安全边界处生效，因此依赖目标目录的工作（读取、编辑、设置命令）应放在下一次调用中。

**为什么不用 cd：**shell 中的 cd 只会更改单条命令的工作目录；session_move 会重新设定会话的 Location 根目录，因此工具调用、配置发现和指令文件都会基于 worktree 检出目录解析。

4. 项目内位置安全（仅适用于位于仓库内部的情况）

当 worktree.directory 将 worktree 放在检出目录内（.worktrees/、worktrees/ 等）时，创建 worktree 之前请确认该目录已被忽略：

git check-ignore -q .worktrees 2>/dev/null || git check-ignore -q worktrees 2>/dev/null

如果未被忽略：将其添加到 .gitignore，然后提交，再创建 worktree。这样可防止 worktree 内容污染 git status，或被意外提交。

5. 运行项目设置

worktree 是全新的检出目录 — 不会与主 worktree 共享依赖项。自动检测并运行设置：

# Node.js
[ -f package.json ] && npm install

# Rust
[ -f Cargo.toml ] && cargo build

# Python
[ -f requirements.txt ] && pip install -r requirements.txt
[ -f pyproject.toml ] && poetry install

# Go
[ -f go.mod ] && go mod download

6. 验证干净的基线并报告

运行项目测试，确认 worktree 初始状态正常：

# project-appropriate: npm test / cargo test / pytest / go test ./...

**如果测试失败：**报告失败情况，并询问是继续还是调查原因。**如果测试通过：**报告已准备就绪。

Worktree ready at <full-path> (branch <name>)
Session moved. Tests passing (<N> tests, 0 failures)
Ready to implement <feature-name>

清理

完成工作后，与 finishing-a-development-branch 搭配使用：

• 使用 worktree 的 directory 调用 worktree_remove，即可移除 opencode 为该项目记录的 worktree。它会对此目录使用 edit 权限；只有在需要丢弃未提交更改时才设置 force: true。
• 未经明确确认，绝不要移除包含未推送、未合并提交的 worktree — 这会导致工作丢失。
• 使用原始 git 手动创建的 worktree（见下方备用方案）不会被 opencode 记录；请改用 git worktree remove <path> 将其移除。

回退方案：原始 Git

仅在以下情况下直接使用 git worktree add：

• 在没有原生工具的环境中运行（Claude Code、Codex、纯终端）。
• 工作树需要使用当前 HEAD 以外的基准（git worktree add <path> -b <branch> <base-commit>）。
• 用户明确要求手动创建工作树。

同样的安全规则仍然适用：检查项目本地路径是否被 gitignore，执行项目设置，运行基线测试，并告知工作树位置。

快速参考

情况	操作
使用 opencode v2	worktree_create → git checkout -b → session_move → 执行设置 → 基线测试
需要非默认位置	在 opencode 配置中设置 worktree.directory
位置在仓库内	先运行 git check-ignore；如果未被忽略，则添加到 .gitignore 并提交
需要使用 HEAD 以外的基准	回退方案：git worktree add <path> -b <branch> <base>
基线测试失败	报告失败情况并询问
工作完成	finishing-a-development-branch → worktree_remove

常见错误

以为 worktree_create 会创建分支

• **问题：**它会保留分离的 HEAD；提交不会落到任何分支上。
• **修复：**创建工作树后，立即在其中运行 git checkout -b <branch>。

进入工作树目录，而不是调用 session_move

• **问题：**只会更改 shell 的当前工作目录；会话、配置和指令发现仍然指向旧位置。
• **修复：**调用 session_move；依赖此操作的工作放到下一轮进行。

在 opencode 中手动运行 git worktree add

• **问题：**opencode 不会记录手动创建的工作树，因此 worktree_list/worktree_remove 无法识别它们，而且工作树位置会忽略 worktree.directory。
• **修复：**在 v2 中使用原生工具；仅在上述回退情况下使用原始 Git。

基线测试失败仍继续

• **问题：**无法区分新问题和既有问题。
• **修复：**报告失败情况，并获得明确许可后再继续。

警示事项

绝不：

• 在分离的 HEAD 上提交（先创建分支）
• 未经确认就移除包含未推送或未合并工作的工作树
• 跳过基线测试验证
• 用户偏好项目本地位置时仍假设使用默认位置——检查或设置 worktree.directory

始终：

• 在 opencode v2 中使用原生工具，仅在回退情况下使用原始 Git
• 创建工作树后，使用 session_move 移动会话
• 检查仓库内位置是否被 gitignore
• 自动检测并执行项目设置，然后运行干净的基线测试

工作流示例

You: I'm using the using-git-worktrees skill to set up an isolated workspace.

[worktree_create name="auth" -> C:\Users\osmon\.local\share\opencode\worktree\c3488b\auth]
[git checkout -b feature/auth]
[session_move directory=<worktree dir>]
[npm install, npm test - 47 passing]

Worktree ready at C:\Users\osmon\.local\share\opencode\worktree\c3488b\auth (branch feature/auth)
Session moved. Tests passing (47 tests, 0 failures)
Ready to implement auth feature

集成

由以下内容调用：

• subagent-driven-development - 执行任何任务前必须调用
• executing-plans - 执行任何任务前必须调用
• 任何需要隔离工作区的技能

搭配使用：

• finishing-a-development-branch - 工作完成后必须用于清理