using-git-worktrees

Git Worktree の使用

概要

worktree は別の Git 履歴を同時にチェックアウトするための例外的な手段であり、一般的な安全性の証明ではありません。現在のワークスペースを優先し、条件に合う既存の worktree を再利用してください。ブランチをどうするかという判断と、worktree をどうするかという判断は別々です。

基本原則： 必要性と所有者を示す根拠がある場合にのみ作成し、作成したすべての worktree にクリーンアップ手順を設定してください。

開始時に宣言すること： worktree が必要となる具体的なチェックアウトの競合を説明してください。

ステップ 0：環境の検出

変更を加える前に、リポジトリのルート、HEAD、ブランチまたは detached の状態、ステージ済み／未ステージ／未追跡のパス、実行中の Git 操作、および以下を記録してください。

git worktree list --porcelain

現在のホスト環境における、タスク／チャットに紐づく管理対象ワークスペースのセマンティクスを managed、non-managed、または unknown に分類してください。信頼できるホスト／セッションのコンテキスト、明示的なホストの契約、またはホストネイティブなライフサイクルの結果を使用してください。製品名、ディレクトリのプレフィックス、コマンドレベルの workdir、ツールの不在、メタデータの欠落から分類を推測してはいけません。non-managed と分類するには、現在の環境にタスクに紐づく管理対象セマンティクスがないという肯定的な根拠が必要です。ホストがワークスペースのフィールドを公開している場合は、タスクのワークスペースと、コマンドごとのディレクトリ上書きがない状態でのコマンドのデフォルトの cwd を記録してください。

未解決の競合がある場合、merge／rebase／cherry-pick／revert／bisect が実行中の場合、または説明できない detached HEAD の場合は停止してください。信頼できるホストのバインド根拠により、それが現在の管理対象 worktree の意図された状態だと特定できる場合に限り、detached HEAD を許容できます。たとえば、Codex 管理の worktree はデフォルトで detached から開始します。ユーザーの状態を保持してください。自動的な stash、reset、clean、広範なステージング、コミットは行わないでください。

必要性や配置を判断する前に、関連する最小限のプロジェクト AGENTS.md、CLAUDE.md、現在有効な規則、および既存の worktree の慣例を確認してください。リポジトリのポリシーで分離が必須または禁止されている場合があり、承認されたリポジトリ内の配置場所はそのポリシーに従います。チェックアウトを作成した後でポリシーを確認してはいけません。

ステップ 1：必要性の判断

次のいずれかに該当する場合に限り、タスク所有の worktree を最大 1 つ作成してください。

• このタスクの作業中も、別のブランチをチェックアウトしたままにしておく必要がある。
• 無関係な変更済みの状態により、現在のワークスペースで安全にチェックアウトできない。
• ユーザーまたは現在有効なリポジトリの規則で明示的に要求されている。

タスクの複雑さ、計画、TDD、サブエージェントの使用、またはブランチ名が main／master であることだけでは、十分な理由になりません。同じタスクのサブエージェントは 1 つのワークスペースを共有してください。サブエージェントごと、または入れ子状の worktree は作成しないでください。独立した履歴が不要であれば、ブランチも作成しないでください。

理由、ブランチ、正確なパス、作成を担当するコーディネーター、および想定するクリーンアップのタイミングを記録してください。所有者またはクリーンアップ条件が不明な場合は、作成前に停止してください。

ステップ 2：安全な配置

既存のリポジトリ内の慣例は、対象ディレクトリがすでに無視対象であること（git check-ignore）を確認できた場合にのみ使用してください。worktree の配置場所を確保するためだけに .gitignore を編集またはコミットしてはいけません。安全なリポジトリ内の慣例がなければ、リポジトリ外にタスク専用の外部ユーザーレベルの一時ディレクトリを使用してください。作成前に正確なパスを解決して確認してください。広範なホームディレクトリ、ワークスペース、またはリポジトリのルートを対象にしてはいけません。

ステップ 3：必要最小限のチェックアウトを作成

同じ目的の既存ブランチの再利用を優先してください。承認された Git のライフサイクルで独立した履歴が必要な場合に限り、ブランチを作成してください。

管理対象ホストのバインドゲート

ホストのサーフェスでタスク／チャットにバインドされた管理対象ワークスペースが宣言されている場合は、シェルで作成するのではなく、ホストネイティブの Worktree／Handoff ライフサイクルを使用します。信頼できるホストの証拠から、現在のタスクが意図したワークスペースにすでにバインドされていると確認できる場合に限り、現在のタスクを再利用します。ネイティブ操作によって別のタスクに作業が作成または移動された場合は、そのバインド先のタスクでのみ作業を続けます。

ネイティブのライフサイクル操作の後、またはすでにバインドされた管理対象ワークスペースに入る／それを再利用する際は直ちに、最初のタスク内容または Git 履歴への書き込みより前に、次の条件をまとめて読み戻します。

• 信頼できるタスクのワークスペース
• コマンドレベルのディレクトリ上書きがない場合のデフォルトの cwd
• 意図した Git worktree のルート
• 意図した HEAD とブランチ／detached 状態

4 つすべてが同じ実行環境を示している必要があります。git worktree list、管理対象に見えるパス、またはコマンドごとの workdir で証明できるのは、この条件の一部だけです。ネイティブの作成／引き継ぎが利用できない、UI 操作のみである、または検証できない場合は、シェルでの worktree 作成やタスク内容／履歴への書き込みを行う前に停止し、ホストネイティブの再入場操作をユーザーに案内します。git worktree add に黙ってフォールバックしてはいけません。 パスの同一性は、パス文字列をそのまま比較するのではなく、ホストに適した方法で解決して比較します。デフォルトの cwd は worktree のルートと同じでも、その配下でもかまいません。そのデフォルトの cwd から Git を実行したときに、意図した worktree のルートが解決される必要があります。 ホストが管理する detached HEAD が意図された状態であれば、Git 状態の条件を満たします。その状態を一般的なチェックアウトのように見せるためだけにブランチを作成してはいけません。

バインドされていない手動 worktree がすでに存在する場合は保持し、その正確なパス、HEAD、ブランチ、ステータス、所有権を示す証拠を報告します。変更済み、未追跡、または所有権が不明な状態を自動的に移行、削除、stash、リセット、上書きしてはいけません。後でコミット／パッチを転送する場合は、通常の Git の認可に従い、クリーンアップを提案する前に新しいバインド先のタスクで検証する必要があります。

一般的な Git フォールバック

以下のシェル手順を使用できるのは、信頼できる証拠により、現在のホスト／CLI サーフェスが non-managed と明確に分類されている場合のみです。unknown の分類では安全側に倒して処理を中止します。ネイティブツールがないことやバインドメタデータがないことは、一般的なフォールバックを選ぶ根拠にはなりません。

# Existing branch
git worktree add <exact-path> <branch>

# New independently justified branch
git worktree add -b <branch> <exact-path> <start-point>

git worktree list --porcelain、新しい worktree の HEAD／ブランチ、およびそのステータスを読み戻します。強制フラグは使用しません。一般的なホストでは、コマンドレベルの workdir でこのチェックアウトを指定できますが、それによって管理対象タスクへのバインドが証明されることはありません。

Step 4: 権威ある情報に基づくセットアップとベースライン

プロジェクトのインストール手順、ロックファイル、既存のセットアップスクリプトを確認します。プロジェクトが明示的に必要としているセットアップのみを実行します。マニフェストが存在するというだけで、npm install、cargo build、pip install、poetry install、または依存関係のダウンロードが必要だと推測してはいけません。

関連するベースライン検証を最小限実行します。セットアップまたはテストが失敗した場合は、正確な失敗内容を報告し、無関係なファイルを変更して失敗を隠さず、worktree を保持します。

Step 5: 引き継ぎとクリーンアップの責任

正確なパス、ブランチ、開始時の HEAD、ベースライン結果、所有者、クリーンアップの開始条件を報告します。作成を担当したコーディネーターは、クリーンアップを実行したことを証明するか、責任を明示的に引き継ぐまで責任を負います。

タスクのコミットまたは統合の判断後に finishing-a-development-branch を使用します。通常、未マージのブランチを残したまま worktree を削除できます。オープン中の PR があっても、チェックアウトを恒久的に残す必要はありません。

注意すべき兆候

次のことは決して行ってはいけません。

• タスクがコードを変更するという理由だけで worktree を作成する
• worktree の作成を可能にするためだけに .gitignore を変更する
• 依存関係を無条件にインストールする
• サブエージェントごとに worktree を作成する
• Git の読み戻し、パスのプレフィックス、またはコマンドレベルの workdir を、管理対象タスクへのバインドの証拠として扱う
• ホストネイティブの機能が保留中、UI 操作のみ、または初期ツール一覧にないというだけで、シェルによる worktree 作成を行う
• 定例の整理としてグローバルな prune や強制クリーンアップを実行する
• 変更済み、未追跡、ロック中、ユーザー所有、または所有権不明のリソースを削除する

統合

必要性の判断後に限り、計画／実行ワークフローから条件付きで呼び出されます。根拠に基づくクリーンアップのため、finishing-a-development-branch と組み合わせて使用します。