OpenCode Worktree ガイド: Git で作業を安全に分離する

Git worktree は、同じリポジトリに接続された別の作業ディレクトリです。メインの checkout を main に置いたまま、隣のフォルダーで work/auth を checkout できます。ファイルと選択中のブランチは分かれますが、Git のオブジェクトと履歴は共有されるため、作業ごとの clone は通常不要です。

この流れに OpenCode 専用の worktree モードは必要ありません。新しいディレクトリから CLI を起動すると、その場所がプロジェクトのコンテキストになります。グローバル設定は適用されることがありますが、未追跡ファイルやローカル環境が自動でコピーされるわけではありません。

まず現在の checkout のブランチと変更を確認します。きれいな開始状態なら、新しい作業に由来する差分を見分けやすくなります。リポジトリのルートから新しいブランチを作り、元のディレクトリの外側にある兄弟フォルダーへ checkout します。

次の例は現在の commit から work/auth を作り、../app-auth に配置します。ブランチがすでにある場合は、別の worktree で checkout されていないことを確認してください。Git は同じブランチを複数のリンク worktree で同時に使うことを通常は防ぎます。

メインリポジトリのルートから実行します。新しい branch は現在の commit から始まります。

git status --short --branch
git worktree add -b work/auth ../app-auth
cd ../app-auth
opencode
git worktree list
git -C ../app-auth status --short --branch

cd ../app-auth の後、そのシェルで opencode を実行します。現在のディレクトリが重要な境界です。worktree ごとに別のターミナルやセッションを使い、ファイル編集を許可する前にプロジェクトのルートを確認します。最初はブランチと確認対象ファイルを要約させるなど、読み取りだけの依頼が安全です。

セッションごとに範囲の狭い作業を割り当て、ブランチ名をメモします。一方で認証テスト、もう一方でドキュメントを担当できます。同じファイルや生成先を二つのセッションから同時に変更しないでください。ディレクトリを分けても、複数エージェントの調整は自動化されません。

worktree は Git 管理下のファイルと index を分けますが、コンテナーやセキュリティ境界ではありません。ローカル DB、テストサーバー、cache、Docker project、外部アカウントは複数セッションで共有される場合があります。必要なら DB/schema、port、project 名、使い捨て環境を分けてください。

Git が checkout するのは選んだ commit に追跡されたファイルです。.env、証明書、cache、build output などの未追跡・ignore ファイルは新しい worktree に現れるとは限りません。必要な環境だけ再設定し、秘密情報は承認済みの方法で読み込み、git status --short --branch を作業前後に確認します。

worktree のブランチは独立した変更としてレビューします。git diff を確認し、そのディレクトリから必要なテストを実行して、意図したファイルだけが含まれることを確かめます。テスト後はチームの通常手順で merge または rebase します。commit を共有するまでは、別 checkout に変更は現れません。

削除前に未 commit の変更を確認し、commit、stash、保管のどれにするか決めます。git worktree remove ../app-auth は clean な checkout を削除します。変更があると Git は force なしでは拒否します。force を通常の掃除に使わないでください。手作業でフォルダーを消した後の git worktree prune は古い登録を整理します。

ブランチ、ファイルの snapshot、数時間から数日残すレビュー境界を分けたいときは worktree が向いています。読み取り調査や未 commit のファイルを見たい作業には、同じ checkout の別セッションが簡単です。作業が順番に進み、一つのディレクトリだけが必要なら通常の branch 切り替えで足ります。

worktree では branch 命名、依存関係、サービス分離、テスト、merge、削除の管理が増えます。複数エージェントが同じファイルを編集するなら、最終 merge が難しくなることがあります。重ならない変更に分けるか、編集を順番に行ってください。

git worktree add が branch 使用中と表示したら、git worktree list を見て別 branch を作るか既存 worktree に戻ります。OpenCode のファイルが想定と違う場合は、設定を変える前に terminal の場所と project root を確認してください。ignore や未追跡ファイルは checkout に含まれません。

テストがセッション間で干渉する場合は、Git の外側を確認します。DB、port、一時フォルダー、generator、共有 cache が原因になりやすいです。削除ができない場合は worktree 内で git status を実行し、必要な変更を保存してから整理します。main の checkout は統合用に残しておきます。