using-git-worktrees

Git Worktree の使用

概要

作業が分離されたワークスペースで行われるようにします。プラットフォーム標準の worktree ツールを優先してください。標準ツールが利用できない場合に限り、手動で git worktree を使用します。

基本原則： まず既存の分離状態を確認します。次に標準ツールを使い、最後に git に切り替えます。ハーネスに逆らわないでください。

開始時に伝えること： 「using-git-worktrees スキルを使って、分離されたワークスペースを設定します。」

ステップ 0：既存の分離状態を確認する

何かを作成する前に、すでに分離されたワークスペース内にいるか確認してください。

GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
BRANCH=$(git branch --show-current)

サブモジュールの確認： GIT_DIR != GIT_COMMON は git サブモジュール内でも成立します。「すでに worktree 内にいる」と判断する前に、サブモジュール内ではないことを確認してください。

# If this returns a path, you're in a submodule, not a worktree — treat as normal repo
git rev-parse --show-superproject-working-tree 2>/dev/null

GIT_DIR != GIT_COMMON の場合（サブモジュールではない場合）： すでにリンクされた worktree 内にいます。ステップ 2（プロジェクトのセットアップ）に進んでください。別の worktree を作成してはいけません。

ブランチの状態とともに報告します。

• ブランチ上にいる場合：「すでに <path> の分離されたワークスペース内にいます。ブランチは <name> です。」
• Detached HEAD の場合：「すでに <path> の分離されたワークスペース内にいます（Detached HEAD、外部で管理されています）。完了時にブランチを作成する必要があります。」

GIT_DIR == GIT_COMMON の場合（またはサブモジュール内の場合）： 通常のリポジトリをチェックアウトした状態です。

ユーザーは指示の中で、すでに worktree の希望を示していますか？示していない場合は、worktree を作成する前に同意を求めてください。

「分離された worktree を設定しましょうか？現在のブランチを変更から保護できます。」

すでに表明されている希望があれば、確認せずに従ってください。ユーザーが同意しない場合は、現在の場所で作業し、ステップ 2 に進んでください。

ステップ 1：分離されたワークスペースを作成する

方法は 2 つあります。次の順番で試してください。

1a. 標準の Worktree ツール（推奨）

ユーザーは分離されたワークスペースを希望しています（ステップ 0 で同意済み）。worktree を作成する方法はすでにありますか？EnterWorktree、WorktreeCreate のような名前のツール、/worktree コマンド、または --worktree フラグなどが考えられます。利用できる場合はそれを使い、ステップ 2 に進んでください。

標準ツールはディレクトリの配置、ブランチの作成、クリーンアップを自動的に処理します。標準ツールが使えるのに git worktree add を使うと、ハーネスから認識も管理もできないファントム状態が発生します。

標準の worktree ツールが利用できない場合に限り、ステップ 1b に進んでください。

1b. Git Worktree による代替手段

ステップ 1a を適用できない場合に限り使用してください — 標準の worktree ツールが利用できない場合です。git を使って手動で worktree を作成します。

ディレクトリの選択

次の優先順位に従ってください。ユーザーが明示した希望は、常に確認できたファイルシステムの状態より優先されます。

1. worktree ディレクトリに関する希望が指示に記載されているか確認します。 ユーザーがすでに指定している場合は、確認せずにその場所を使用してください。

2. 既存のプロジェクト内 worktree ディレクトリを確認します。

   ls -d .worktrees 2>/dev/null     # Preferred (hidden)
   ls -d worktrees 2>/dev/null      # Alternative
   

   見つかった場合はそれを使用します。両方ある場合は .worktrees を優先します。

3. ほかに指示がない場合は、プロジェクトのルートにある .worktrees/ を既定の場所とします。

安全性の確認（プロジェクト内ディレクトリのみ）

worktree を作成する前に、ディレクトリが ignore 対象であることを必ず確認してください。

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

ignore 対象ではない場合： .gitignore に追加して変更をコミットしてから、続行してください。

重要な理由： worktree の内容を誤ってリポジトリにコミットするのを防ぎます。

Worktree の作成

# Determine path based on chosen location
path="$LOCATION/$BRANCH_NAME"

git worktree add "$path" -b "$BRANCH_NAME"
cd "$path"

サンドボックスで失敗した場合の代替手段： git worktree add が権限エラー（サンドボックスによる拒否）で失敗した場合は、サンドボックスによって worktree の作成がブロックされたため、代わりに現在のディレクトリで作業することをユーザーに伝えてください。その後、現在の場所でセットアップとベースラインテストを実行します。

ステップ 2：プロジェクトのセットアップ

適切なセットアップ方法を自動検出して実行します。

# Node.js
if [ -f package.json ]; then npm install; fi

# Rust
if [ -f Cargo.toml ]; then cargo build; fi

# Python
if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
if [ -f pyproject.toml ]; then poetry install; fi

# Go
if [ -f go.mod ]; then go mod download; fi

ステップ 3：クリーンなベースラインを確認する

ワークスペースがクリーンな状態で開始できることを確認するため、テストを実行します。

# Use project-appropriate command
npm test / cargo test / pytest / go test ./...

テストが失敗した場合： 失敗内容を報告し、続行するか調査するかを尋ねてください。

テストが成功した場合： 準備完了と報告してください。

報告

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

クイックリファレンス

状況	対応
すでにリンクされたワークツリー内にいる	作成をスキップします（ステップ 0）
サブモジュール内にいる	通常のリポジトリとして扱います（ステップ 0 のガード）
ネイティブのワークツリーツールが利用可能	それを使用します（ステップ 1a）
ネイティブツールがない	Git worktree で代替します（ステップ 1b）
.worktrees/ が存在する	それを使用します（無視対象であることを確認）
worktrees/ が存在する	それを使用します（無視対象であることを確認）
両方存在する	.worktrees/ を使用します
どちらも存在しない	指示ファイルを確認してから、既定の .worktrees/ を使用します
ディレクトリが無視対象でない	.gitignore に追加してコミットします
作成時に権限エラーが発生する	サンドボックスで代替し、その場で作業します
ベースラインのテストが失敗する	失敗を報告して、確認を求めます
package.json/Cargo.toml がない	依存関係のインストールをスキップします

よくある誤った判断

言い訳	実際のところ
「明らかにワークツリー内ではない。確認する必要はない」	ステップ 0 を実行します。ハーネスが作成した隔離環境もサブモジュールも、目視では判断を誤りやすいため、検出コマンドで確認します。
「ネイティブツールを探すより git worktree add のほうが早い」	EnterWorktree などのネイティブツールは、配置、ブランチ作成、クリーンアップを管理します。それを使わないのが最大の間違いです。ハーネスから見えず、管理もできない幻の状態が作られます。
「ワークツリーのディレクトリは、きっとすでに無視対象になっている」	git check-ignore を実行します。ワークツリーのディレクトリが無視対象でないと、ツリー全体がリポジトリにコミットされてしまいます。
「ディレクトリ名は何でもよい」	明示的な指示は既存のプロジェクト内ディレクトリより優先され、既存のプロジェクト内ディレクトリは .worktrees/ の既定値より優先されます。
「ワークスペースは新しいので、ベースラインテストは後回しでよい」	ベースラインが汚れていると、その後の失敗すべての原因が曖昧になります。今すぐテストを実行してください。失敗を無視して先に進むかどうかは、人間のパートナーが判断します。