using-git-worktrees

Git Worktree の使用

概要

Git worktree は、同じリポジトリを共有する分離されたワークスペースを作成するため、ブランチを切り替えずに複数のブランチで同時に作業できます。

基本原則： opencode v2 では、ネイティブの worktree_* ツールを使って worktree を作成し、シェルだけでなく セッション を worktree に移動します。これにより、opencode の追跡機能（一覧表示／削除）、プロジェクト設定、AGENTS.md の検出先が適切な場所を指すようになります。

開始時に伝える： 「using-git-worktrees スキルを使って、分離されたワークスペースをセットアップします。」

デフォルトの方法：ネイティブの Worktree ツール

opencode v2 内で実行する場合（通常はこちら）に使用します。ツールは worktree_create、worktree_list、worktree_remove（Code Mode の名前空間 opencode）、および session_move です。

1. Worktree を作成する

name を指定して worktree_create を呼び出します。機能名／ブランチ名（例：auth、fix-login-timeout）を使用してください。戻り値は { directory } です。

worktree の配置先は、スキルではなく、プロジェクトの opencode 設定にある worktree.directory 設定で決まります。

• 未設定（デフォルト）： opencode のデータディレクトリである worktree/<project-id prefix>/<name> に配置されます。リポジトリの外なので、gitignore に追加する必要はありません。
• 設定済み（例："worktree": { "directory": ".worktrees" }）：相対パスはプロジェクトの正規チェックアウトを基準に解決されます。ディレクトリがリポジトリの 内部 にある場合は、gitignore に追加する必要があります（以下を参照）。

git worktree add で配置場所を独自に決めないでください。opencode が記録・管理するのは opencode 自身が作成した worktree だけなので、手動で作成したものは worktree_list／worktree_remove から認識できません。

ユーザーがデフォルト以外の場所を希望する場合、v2 に沿った方法は、セッションごとにパスを選ぶのではなく、設定で worktree.directory を指定することです（その設定を AGENTS.md またはメモにも記載してください）。

2. ブランチを作成する

worktree_create はブランチ名を受け取りません。新しい worktree は、リポジトリの現在のコミットを指す detached HEAD で作成されます。worktree 内でブランチを作成してください。

git checkout -b "<branch-name>"

（git checkout main は失敗します。main はすでにメインの worktree でチェックアウトされているためです。これは想定どおりであり、エラーではありません。）

3. セッションを Worktree に移動する

worktree のディレクトリを directory として指定し、session_move を呼び出します。移動は安全なタイミングで反映されるため、移動先に依存する作業（読み取り、編集、セットアップコマンド）は次の呼び出しで行います。

cd ではなくこちらを使う理由： シェルの cd は1つのコマンドの作業ディレクトリだけを変更しますが、session_move はセッションの Location を再設定するため、ツール呼び出し、設定の検出、指示ファイルの参照先がすべて worktree のチェックアウトに基づいて解決されます。

4. プロジェクト内の配置場所の安全性を確認する（リポジトリ内の場合のみ）

worktree.directory によってチェックアウト内（.worktrees/、worktrees/、…）に worktree が配置される場合は、worktree を作成する前にそのディレクトリが無視対象になっていることを確認します。

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

無視対象になっていない場合は、そのディレクトリを .gitignore に追加してコミットしてから作成します。これにより、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_remove に worktree の directory を指定すると、そのプロジェクト用に 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>）。
• ユーザーが手動での worktree 作成を明示的に依頼した場合。

同じ安全ルールが適用されます。プロジェクト内のパスについて 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 がブランチを作成すると考える

• 問題： detached HEAD の状態になり、ブランチが指していないため、コミットがどのブランチにも反映されません。
• 修正： 作成直後に、worktree 内で git checkout -b <branch> を実行します。

session_move の代わりに worktree へ cd する

• 問題： シェルの CWD だけが変わり、セッション、設定、指示の検出先は以前の場所のままです。
• 修正： session_move を呼び出し、依存する作業は次のターンで行います。

opencode で git worktree add を手作業で実行する

• 問題： opencode は手動で作成した worktree を記録しないため、worktree_list／worktree_remove で確認できず、場所も worktree.directory の設定に従いません。
• 修正： v2 ではネイティブツールを使用します。生の Git は上記のフォールバックケースでのみ使用します。

ベースラインテストが失敗しているのに作業を続ける

• 問題： 新たなバグと既存の問題を区別できません。
• 修正： 失敗を報告し、続行する明示的な許可を得ます。

危険な兆候

絶対にしないこと：

• detached HEAD でコミットする（先にブランチを作成してください）
• 未プッシュまたは未マージの作業がある worktree を、確認なしに削除する
• ベースラインテストの確認を省略する
• ユーザーがプロジェクト内の場所を希望しているのに、デフォルトの場所を使う（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 - 作業完了後のクリーンアップに必須