git-worktree

Git Worktree Manager

このスキルは、開発ワークフロー全体で Git worktree を管理するための統一インターフェースを提供します。PR を分離してレビューする場合も、複数の機能を並行して開発する場合も、複雑な処理はこのスキルが担います。

このスキルでできること

• worktree を作成：main ブランチから、わかりやすいブランチ名で作成します
• worktree を一覧表示：現在の状態を確認できます
• worktree を切り替え：並行作業を進められます
• 完了した worktree を自動でクリーンアップ
• 各ステップで対話形式の確認
• worktree ディレクトリ用の .gitignore を自動管理
• main リポジトリから新しい worktree へ .env ファイルを自動コピー
• レビュー時の安全策を備え、mise と direnv の設定を自動で信頼

重要：必ず Manager スクリプトを使ってください

git worktree add を直接実行しないでください。 必ず worktree-manager.sh スクリプトを使ってください。

このスクリプトは、通常の git コマンドでは実行されない重要なセットアップ処理を行います。

1. main リポジトリから .env、.env.local、.env.test などをコピーします
2. ブランチを考慮した安全ルールに従って、開発ツールの設定を信頼します：
   • mise：信頼済みのベースブランチから変更されていない場合に限り、自動で信頼します
   • direnv：信頼済みのベースブランチのみ自動で許可します。レビュー用 worktree では手動のままにします
3. .worktrees が .gitignore に含まれていることを確認します
4. 一貫したディレクトリ構造を作成します

# ✅ CORRECT - Always use the script
bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh create feature-name

# ❌ WRONG - Never do this directly
git worktree add .worktrees/feature-name -b feature-name main

このスキルを使う場面

次のような場面でこのスキルを使います。

1. コードレビュー（/ce:review）：対象ブランチ（PR ブランチまたは指定されたブランチ）にすでにいる場合を除き、レビューを分離して行うための worktree を提案します
2. 機能開発（/ce:work）：並行用 worktree で作業するか、現在のブランチで作業するかを必ずユーザーに尋ねます
3. 並行開発：複数の機能を同時に開発する場合
4. クリーンアップ：worktree での作業完了後

使い方

Claude Code のワークフローで使う

このスキルは /ce:review コマンドと /ce:work コマンドから自動的に呼び出されます。

# For review: offers worktree if not on PR branch
# For work: always asks - new branch or worktree?

手動で使う

bash からこのスキルを直接呼び出すこともできます。

# Create a new worktree (copies .env files automatically)
bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh create feature-login

# List all worktrees
bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh list

# Switch to a worktree
bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh switch feature-login

# Copy .env files to an existing worktree (if they weren't copied)
bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh copy-env feature-login

# Clean up completed worktrees
bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh cleanup

コマンド

create <branch-name> [from-branch]

指定したブランチ名で新しい worktree を作成します。

オプション：

• branch-name（必須）：新しいブランチと worktree の名前
• from-branch（任意）：作成元のベースブランチ（デフォルトは main）

例：

bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh create feature-login

実行される処理：

1. worktree がすでに存在するか確認します
2. リモートからベースブランチを更新します
3. 新しい worktree とブランチを作成します
4. main リポジトリからすべての .env ファイルをコピーします（.env、.env.local、.env.test など）
5. ブランチを考慮した安全ルールに従って、開発ツールの設定を信頼します：
   • 信頼済みのベース（main、develop、dev、trunk、staging、release/*）は、それぞれのブランチと比較します
   • それ以外のブランチは、デフォルトブランチと比較します
   • .envrc が未確認のファイルを読み込む可能性があるため、信頼されていないベースでは direnv の自動許可をスキップします
6. worktree に移動するためのパスを表示します

list または ls

利用可能なすべての worktree と、それぞれのブランチおよび現在の状態を一覧表示します。

例：

bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh list

出力項目：

• worktree 名
• ブランチ名
• 現在の worktree（✓ で表示）
• main リポジトリの状態

switch <name> または go <name>

既存の worktree に切り替えて、そのディレクトリへ移動します。

例：

bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh switch feature-login

任意：

• 名前を指定しない場合は、利用可能な worktree を一覧表示し、選択を求めます

cleanup または clean

確認を行いながら、非アクティブな worktree を対話形式でクリーンアップします。

例：

bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh cleanup

実行される処理：

1. 非アクティブな worktree をすべて一覧表示します
2. 確認を求めます
3. 選択した worktree を削除します
4. 空のディレクトリをクリーンアップします

ワークフローの例

worktree を使ったコードレビュー

# Claude Code recognizes you're not on the PR branch
# Offers: "Use worktree for isolated review? (y/n)"

# You respond: yes
# Script runs (copies .env files automatically):
bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh create pr-123-feature-name

# You're now in isolated worktree for review with all env vars
cd .worktrees/pr-123-feature-name

# After review, return to main:
cd ../..
bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh cleanup

機能の並行開発

# For first feature (copies .env files):
bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh create feature-login

# Later, start second feature (also copies .env files):
bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh create feature-notifications

# List what you have:
bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh list

# Switch between them as needed:
bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh switch feature-login

# Return to main and cleanup when done:
cd .
bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh cleanup

主な設計原則

KISS（シンプルに保つ）

• 1 つの Manager スクリプトですべての worktree 操作を処理します
• シンプルなコマンドと適切なデフォルト値を提供します
• 対話形式のプロンプトで誤操作を防ぎます
• ブランチ名をそのまま使うわかりやすい命名

意見を反映したデフォルト設定

• 特に指定がない限り、worktree は main から常に作成されます
• worktree は .worktrees/ ディレクトリに保存されます
• ブランチ名が worktree 名になります
• .gitignore は自動的に管理されます

安全性を最優先

• worktree の作成前に確認します
• 誤って削除しないよう、クリーンアップの前に確認します
• 現在の worktree は削除しません
• 問題が発生した場合は明確なエラーメッセージを表示します

ワークフローとの連携

/ce:review

常に worktree を作成するのではなく、次のようにします。

1. Check current branch
2. If ALREADY on target branch (PR branch or requested branch) → stay there, no worktree needed
3. If DIFFERENT branch than the review target → offer worktree:
   "Use worktree for isolated review? (y/n)"
   - yes → call git-worktree skill
   - no → proceed with PR diff on current branch

/ce:work

常に選択肢を提示します。

1. Ask: "How do you want to work?
   1. New branch on current worktree (live work)
   2. Worktree (parallel work)"

2. If choice 1 → create new branch normally
3. If choice 2 → call git-worktree skill to create from main

トラブルシューティング

「Worktree already exists」

このメッセージが表示された場合、スクリプトからその worktree に切り替えるかどうかを尋ねられます。

「Cannot remove worktree: it is the current worktree」

まず worktree から切り替えて（メインリポジトリに移動して）から、クリーンアップしてください。

cd $(git rev-parse --show-toplevel)
bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh cleanup

worktree 内で現在地がわからなくなった場合

現在地を確認します。

bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh list

worktree に .env ファイルがない場合

worktree が .env ファイルなしで作成された場合（例：git worktree add を直接実行した場合）は、ファイルをコピーしてください。

bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh copy-env feature-name

メインに戻ります。

cd $(git rev-parse --show-toplevel)

技術的な詳細

ディレクトリ構成

.worktrees/
├── feature-login/          # Worktree 1
│   ├── .git
│   ├── app/
│   └── ...
├── feature-notifications/  # Worktree 2
│   ├── .git
│   ├── app/
│   └── ...
└── ...

.gitignore (updated to include .worktrees)

仕組み

• 分離された環境を作成するために git worktree add を使用します
• 各 worktree には独自のブランチがあります
• ある worktree での変更は、ほかの worktree に影響しません
• メインリポジトリと Git の履歴を共有します
• どの worktree からでもプッシュできます

パフォーマンス

• worktree は軽量です（ファイルシステムのリンクのみです）
• リポジトリを複製しません
• 効率化のため、Git オブジェクトを共有します
• クローンや stash／ブランチ切り替えよりも大幅に高速です