git-worktree

Git ワークツリー管理ツール

ゲート：タスクが既存のワークツリー内で実行されている場合（ワークツリーのパスが示されており、作成・削除・切り替えが要求されていない場合）、作成フローは適用されません。そのまま作業し、このスキルをスキップしてください。 確認方法：git worktree list に、git rev-parse --show-toplevel の結果がリンクされたエントリーとして表示されます。

作業ルール

• 他のセッションのブランチ、ファイル、ステージ済みの作業を保持してください（「所有権」を参照）。
• 依存関係が、意図したワークツリー内のファーストパーティコードを参照していることを確認してください。
• マージ、プッシュ、クリーンアップはユーザーの承認範囲内で行い、実際に使用したチェックアウトと作成されたコミットを正確に報告してください。

必ず管理スクリプトを使用する

git worktree add を直接呼び出してはいけません。必ず worktree-manager.sh スクリプトを使用してください。

管理スクリプトはセットアップを処理します。

1. メインチェックアウトの .env、.env.local、.env.test などをコピーします。ただし、ベースがデフォルトブランチ、またはフェッチ済みコミットをすでに含むローカルブランチの場合に限ります（origin にしか存在しないブランチからはコピーしません）。新しいツリーに既存のファイルやシンボリックリンクがある場合は、上書きも追跡もしません。
2. メインチェックアウトの .gitignore に .worktrees が含まれるようにします。
3. 一貫したディレクトリ構造を作成します。
4. 作成後、検出された依存関係をインストールします。package.json → npm install、composer.json → composer install、pyproject.toml → pip install -e .、go.mod → go mod download

信頼できないベース（PR のヘッド、フォークまたは origin にのみ存在するブランチ、サードパーティコード）： --no-env を指定して作成し、ツリーに copy-env を実行せず、認証情報をコマンドに含めないでください。インストールはスキップしてください。必要な場合は、ライフサイクルスクリプトとプラグインを無効にします（npm ci --ignore-scripts、composer install --no-scripts --no-plugins）。ビルドバックエンドが実行されるため、pip install -e . は決して実行しないでください。

すべてのコマンドで次を使用します。bash ${CLAUDE_PLUGIN_ROOT}/skills/ia-git-worktree/scripts/worktree-manager.sh <command>。CLAUDE_PLUGIN_ROOT が設定されていない場合（Claude Code 以外のハーネス）は、このスキルのディレクトリを基準にスクリプトのパスを解決してください。

ワークツリーを作成する前に、一意の WORKTREE_SESSION_ID をエクスポートし、このセッションで後から管理スクリプトを呼び出すときも同じ値を保持してください。例：export WORKTREE_SESSION_ID="$(python3 -I -c 'import uuid; print(uuid.uuid4())')"。管理スクリプトは、新しいワークツリーの Git メタデータに所有権を記録します。セッション ID なしでも作成できますが、その場合、管理スクリプトによるクリーンアップでそのツリーは拒否されます。所有権を回避するために、以前のセッションの ID を使い回してはいけません。

管理スクリプトは <base> を origin から呼び出しごとに固有のプライベート参照へフェッチし、そのコミットを解決して、origin/<base> が存在しない場合や古い場合、または別のチェックアウトが同時にフェッチしている場合でも、その SHA からブランチを作成します。削除するのは自身のプライベート参照だけで、呼び出し元の作業ツリーで <base> をチェックアウトすることはありません。フェッチに失敗した場合（オフライン、リモートなし）は、代わりにローカルの <base> を解決します。PR のレビューでは、フェッチした PR ヘッドを <base> として渡し、その SHA を確認してください（workflow-examples.md）。詳細はtroubleshooting.mdを参照してください。

コマンド

コマンド	説明	例
create [--no-env] <branch> [from]	worktree とブランチを作成します（デフォルトは main から作成）	...worktree-manager.sh create feature-login
list / ls	ステータスとともにすべての worktree を一覧表示します	...worktree-manager.sh list
switch <name> / go	登録済み worktree の絶対パスを出力します。呼び出し元がそれを作業ディレクトリとして適用します	target=$(...worktree-manager.sh switch feature-login)
copy-env <name>	既存の worktree に .env ファイルをコピーします	...worktree-manager.sh copy-env feature-login
cleanup <name> [...] / clean	名前で指定した、このセッションが所有する変更のない worktree の削除を確認します	...worktree-manager.sh cleanup feature-login

コマンドは env -C "$target" <command> またはハーネスの workdir 引数を使って実行します。子スクリプトから呼び出し元の作業ディレクトリを変更することはできません。一覧表示と名前解決は、サブディレクトリを含め、main またはリンクされたどのチェックアウトからでも実行できます。

cleanup は、現在のチェックアウト、別のセッションの worktree、追跡済み・未追跡・無視対象のファイルがある worktree の削除を拒否します。そのため、自動コピーされた .env ファイルやインストール済みの依存関係は、cleanup の前にユーザーが明示的に処理する必要があります。指定した worktree を使用するプロセスがないことを確認してください。このマネージャーは、外部の読み取り元をすべて検出できるわけではありません。ロックされた worktree の削除拒否を含め、Git の通常の削除保護は有効のままです。削除を強制したり、cleanup を完了するためにエラーを抑制したりしないでください。

安全性の確認

main のチェックアウトがある場合は、作成前に .worktrees が無視対象になっていることを確認します。

# Verify .worktrees is ignored (should output ".worktrees")
git check-ignore .worktrees || echo "WARNING: .worktrees not in .gitignore"

無視対象になっていない場合は、続行する前に .gitignore に追加してください。

ベースラインのテストスイートやマイグレーションを実行する前に、ia-verification-before-completion の有効な対象に対する事前確認を適用します。worktree の環境・設定オーバーレイを解決し、使い捨てデータベースとサービスの対象を確認してください。開発用データベースは使用しないでください。コピーされた .env ファイルは、分離されていることの証明にはなりません。使い捨て対象であることを確認できない場合は、テストの前に中止してください。その後、実装前のクリーンなベースラインを確立するため、テストスイート全体、または関連する最速のサブセットを実行します。

所有権

• ワークツリーごとに書き込み担当者は1人です。git worktree list にあるうち、現在のセッションで作成していないエントリーはすべて読み取り専用として扱ってください。前回のラウンドから残っているツリーも、現在のセッションのものではありません。既存のツリーには依存関係や環境設定がすでに整っており、別のセッションがそこでテストスイートを実行している可能性もあるため、再利用したくなるのは最も危険な場面です。
• 現在のセッションのテストスイートが実行中のツリーは変更しないでください。テストランナーはソースファイルを順に読み込むため、実行途中の編集は、本物のリグレッションとまったく同じに見える大量失敗を引き起こします。
• 主張と矛盾する一連の失敗は、ハーネスに関する仮説であり、結論ではありません。自分で引き起こしたと断定して記録または報告するのは、git status --short が空であることを確認したばかりのツリーで再実行し、その結果が返ってからにしてください。
• 変更が避けられない場合は、git checkout -- を信用せず、トークンの数を元に戻して grep で確認し、さらに git status --short を確認して、復元できたことを確かめてください。
• 1つのチェックアウトにインデックスは1つだけです。通常のコミットには、無関係なステージ済み項目も含まれます。一方、git commit -- <paths> は呼び出し元や他の担当者による差分を含め、作業ツリー上のファイル全体を記録します。選択した変更すべてのファイル全体を自分が所有していると確認できた場合に限り、パス指定コミットを使用してください。差分が混在している場合は、呼び出し元の HEAD、インデックス、ファイルを保持したまま、自分が所有するクリーンなチェックアウトで自分に帰属するパッチをコミットしてください。ファイル名や --stat だけでなく、提案されたパッチとコミット済みパッチの正確な内容を確認してください。commit-ownership.md を参照してください。
• git -C を使った push では、HEAD: を絶対に使用しないでください。編集したワークツリーで SHA を解決して明示的に push し、git ls-remote で確認してください。リースを使っても、別のチェックアウトの HEAD を選んでしまうことは検出できません。詳細は commit-ownership.md を参照してください。
• 赤／緑テストのために git stash を使わないでください。リンクされたワークツリーでは stash スタックを共有しています。commit-ownership.md に記載されたパッチファイルのサイクルと stash の復元方法を使用してください。
• ブランチに関する質問には、ワークツリーの HEAD ではなく、参照（rev-parse <branch>）を基に回答してください。HEAD は別のセッションによって移動されることがあります。commit-ownership.md を参照してください。

すべてのコマンドで env -C <worktree> <cmd> を使用し、cd は決して使わないでください。シェルの cwd は呼び出し間で維持されます。無関係な理由で一度 cd <repo-root> を実行すると、それ以降のコマンドがすべて気づかないうちに別の場所へ移動します。その結果、調査用ファイルが共有メインツリーに書き込まれ、その中身に対してコマンドが実行されます。また、後片付けのつもりで実行する git checkout -- <path> が、間違ったツリーに対する書き込みになります。git -C の習慣は、インタープリター、テストランナー、リンター、ヒアドキュメントを使った cat > には通用しません。調査用コマンドでは、実行したツリーを出力させてください。

検証

• git worktree list に新しいエントリーが表示される
• .worktrees が ignore されているか、bare の共通ディレクトリ内にある
• ワークツリーに依存関係がインストールされている（信頼できるベースが対象です。信頼できないベースの場合は上記のルールに従ってください）
• ベースラインのテストスイートがワークツリーで成功する

参考資料

• workflow-examples.md - コードレビューと並行開発のワークフロー
• troubleshooting.md - よくある問題、新しいリモートベースの動作、ディレクトリ構造、仕組み
• hooks-and-excludes.md - Husky 使用時のフックの安全性、.git/info/exclude と .gitignore
• commit-ownership.md - ファイル全体のコミットと、差分が混在する場合の分離ステージング
• worktree-manager.sh - 管理スクリプト

タスク固有の参考資料

該当する動作を実装またはレビューする前に、関連する参考資料を読んでください。

• 依存関係の出所、環境への適応、レビュー／作業ワークフロー、ブランチの完了、またはフックについては、worktree-integration.md を参照してください。

該当するトピックに適用される既存の専門的な参考資料：