git-worktrees

Git Worktrees

Agent Skills™ の一部です。googleadsagent.ai™ 提供

説明

Git Worktrees は、複数のチェックアウト済みブランチを別々のディレクトリで同時に管理することで、並行開発を可能にします。変更を一時退避してブランチを切り替える代わりに、エージェントはタスクごとに独立した worktree を作成します。これにより、クリーンなテストベースラインを確保し、コンテキスト切り替えのオーバーヘッドをなくします。各 worktree は、それぞれのブランチに紐づいた完全に独立したワークスペースです。

このスキルは、複数のエージェントが異なるタスクを同時に進める、サブエージェント主導の開発に欠かせません。worktree がなければ、エージェント同士の未コミットの変更が互いに上書きされてしまいます。worktree を使うと、各エージェントは独自のブランチを持つそれぞれのディレクトリで作業し、オーケストレーターが完了した作業をメインのブランチにマージします。

worktree はテストのクリーンなベースラインを確保するのにも役立ちます。ビルド成果物、ローカル設定、未コミットの変更がないクリーンなチェックアウトでテストが通ることを確認したい場合、新しい worktree を使えばその状態をそのまま得られます。worktree のライフサイクルは明示的に管理します。タスク開始時に作成し、完了時に検証し、マージ時に整理します。

使用する状況

• 複数のタスクを互いに干渉させずに並行開発する必要がある場合
• サブエージェントが同時作業のために分離されたファイルシステムを必要とする場合
• ローカルの成果物を含まないクリーンなチェックアウトでテストを実行したい場合
• 機能ブランチの作業中にホットフィックスを行う必要がある場合
• 最良のものを選ぶために、複数の実装を別々のワークスペースで試したい場合
• ブランチ間の動作を並べて比較したい場合

仕組み

graph TD
    A[Main Repo] --> B["git worktree add ../task-1 -b feature/task-1"]
    A --> C["git worktree add ../task-2 -b feature/task-2"]
    A --> D["git worktree add ../hotfix -b hotfix/urgent"]
    B --> E[Agent 1 works in ../task-1]
    C --> F[Agent 2 works in ../task-2]
    D --> G[Agent 3 works in ../hotfix]
    E --> H[PR + Merge]
    F --> H
    G --> H
    H --> I["git worktree remove ../task-1"]
    H --> J["git worktree remove ../task-2"]
    H --> K["git worktree remove ../hotfix"]

各 worktree は、独自のチェックアウト済みブランチを持つ、ディスク上の実際のディレクトリです。ある worktree の変更が、他の worktree に影響することはありません。.git メタデータは共有されるため、どの worktree からでもブランチ操作（push、fetch、log）を通常どおり行えます。

実装

# Create a worktree for a new feature
git worktree add ../feature-auth -b feature/user-auth
cd ../feature-auth
npm install  # Dependencies may differ per branch

# List active worktrees
git worktree list
# /home/user/project        abc1234 [main]
# /home/user/feature-auth   def5678 [feature/user-auth]

# Run tests in a clean worktree
git worktree add ../clean-test --detach HEAD
cd ../clean-test
npm ci && npm test
cd ../project
git worktree remove ../clean-test

# Prune stale worktrees (after branch deletion)
git worktree prune

class WorktreeManager:
    def __init__(self, repo_root):
        self.repo_root = repo_root
        self.worktree_base = Path(repo_root).parent

    def create(self, task_name, base_branch="main"):
        branch = f"feature/{task_name}"
        path = self.worktree_base / task_name
        subprocess.run(
            ["git", "worktree", "add", str(path), "-b", branch, base_branch],
            cwd=self.repo_root, check=True
        )
        return WorktreeContext(path, branch)

    def remove(self, task_name):
        path = self.worktree_base / task_name
        subprocess.run(
            ["git", "worktree", "remove", str(path)],
            cwd=self.repo_root, check=True
        )

    def list_active(self):
        result = subprocess.run(
            ["git", "worktree", "list", "--porcelain"],
            cwd=self.repo_root, capture_output=True, text=True
        )
        return self.parse_worktree_list(result.stdout)

ベストプラクティス

• worktree は、別の worktree ではなく、常にメインリポジトリから作成します
• 新しい worktree ごとに npm ci などを実行します。node_modules は共有されません
• ディスク容量の肥大化を防ぐため、マージ後は速やかに worktree を削除します
• 古い参照を整理するため、定期的に git worktree prune を実行します
• ブランチの用途がわかるよう、worktree ディレクトリには内容を表す名前を付けます
• 同じブランチを複数の worktree で同時にチェックアウトしないでください

プラットフォームの互換性

プラットフォーム	対応状況	備考
Cursor	完全対応	best-of-n-runner は worktree をネイティブに使用します
VS Code	完全対応	マルチルートワークスペースをサポートします
Windsurf	完全対応	シェルベースの worktree 管理に対応します
Claude Code	完全対応	Git に直接アクセスします
Cline	完全対応	ターミナルから Git コマンドを実行します
aider	完全対応	任意の worktree ディレクトリから利用できます

関連スキル

• サブエージェント主導の開発 - エージェント間のファイルシステム分離に worktree を利用する、並行タスクのディスパッチ
• 計画の実行 - クリーンな検証ベースラインの確保に worktree を利用する、ロールバック機能付きの計画実行
• コードレビュー - マージ前に各 worktree ブランチへ適用する、マージ前の品質ゲート

キーワード

git-worktrees parallel-development isolated-workspace clean-baseline concurrent-branches subagent-isolation best-of-n branch-management

---

© 2026 googleadsagent.ai™ | Agent Skills™ | MIT License