mcpField
G
git-worktrees

git-worktrees

github.com/neolabhq開発1.8k1.2k 回インストール9 週間前に更新
リポジトリ

git-worktrees について

複数ブランチを同時にチェックアウトしたい開発者向けの Git worktree ガイドです。作成や保守、比較、並行作業の手順を共有リポジトリを前提に説明します。

主な機能

  1. 01リンクされた worktree の作成と管理
  2. 02worktree の一覧表示、移動、ロック、削除
  3. 03古いメタデータの整理とリンクの修復
  4. 04ファイル比較と変更の選択的な移行
  5. 05並行開発とレビューのパターン

活用シーン

  1. 01機能開発中にホットフィックスを並行する
  2. 02現在の作業ツリーに影響せず PR をレビューする
  3. 03分離した worktree でテストを実行する
  4. 04ブランチ間の実装を比較する

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/neolabhq/context-engineering-kit --skill git-worktrees

インストール後、Claude Code で/git-worktreesを入力して読み込まれたか確認します。

詳細

Git ワークツリー

概要

Git ワークツリーを使うと、同じリポジトリを共有しながら、別々のディレクトリで複数のブランチを同時にチェックアウトできます。変更をスタッシュしたり、別途クローンしたりする代わりに、ワークツリーを作成できます。

基本原則： アクティブなブランチごとにワークツリーを1つ作成します。ブランチを切り替えるのではなく、ディレクトリを変更して作業対象を切り替えます。

基本概念

概念説明
メインワークツリーgit clone または git init で作成された元の作業ディレクトリ
リンクされたワークツリーgit worktree add で作成された追加のディレクトリ
共有される .gitすべてのワークツリーが同じ Git オブジェクトデータベースを共有します（重複はありません）
ブランチのロック各ブランチは、一度に1つのワークツリーでのみチェックアウトできます
ワークツリーのメタデータリンクされたワークツリーを追跡する、.git/worktrees/ 内の管理ファイル

クイックリファレンス

タスクコマンド
ワークツリーを作成（既存のブランチ）git worktree add <path> <branch>
ワークツリーを作成（新しいブランチ）git worktree add -b <branch> <path>
ワークツリーを作成（参照から新しいブランチ）git worktree add -b <branch> <path> <start>
デタッチ状態のワークツリーを作成git worktree add --detach <path> <commit>
すべてのワークツリーを一覧表示git worktree list
ワークツリーを削除git worktree remove <path>
ワークツリーを強制削除git worktree remove --force <path>
ワークツリーを移動git worktree move <old> <new>
ワークツリーをロックgit worktree lock <path>
ワークツリーのロックを解除git worktree unlock <path>
古いワークツリーを整理git worktree prune
ワークツリーのリンクを修復git worktree repair
ワークツリー間でファイルを比較diff ../worktree-a/file ../worktree-b/file
別のブランチからファイルを取得git checkout <branch> -- <path>
ファイルの一部の変更を取得git checkout -p <branch> -- <path>
コミットをチェリーピックgit cherry-pick <commit>
コミットせずにチェリーピックgit cherry-pick --no-commit <commit>
自動コミットせずにマージgit merge --no-commit <branch>

基本コマンド

ワークツリーを作成
# Create worktree with existing branch
git worktree add ../feature-x feature-x

# Create worktree with new branch from current HEAD
git worktree add -b new-feature ../new-feature

# Create worktree with new branch from specific commit
git worktree add -b hotfix-123 ../hotfix origin/main

# Create worktree tracking remote branch
git worktree add --track -b feature ../feature origin/feature

# Create worktree with detached HEAD (for experiments)
git worktree add --detach ../experiment HEAD~5
ワークツリーを一覧表示
# Simple list
git worktree list

# Verbose output with additional details
git worktree list -v

# Machine-readable format (for scripting)
git worktree list --porcelain

出力例：

/home/user/project           abc1234 [main]
/home/user/project-feature   def5678 [feature-x]
/home/user/project-hotfix    ghi9012 [hotfix-123]
ワークツリーを削除
# Remove worktree (working directory must be clean)
git worktree remove ../feature-x

# Force remove (discards uncommitted changes)
git worktree remove --force ../feature-x
ワークツリーを移動
# Relocate worktree to new path
git worktree move ../old-path ../new-path
ワークツリーをロック／ロック解除
# Lock worktree (prevents pruning if on removable storage)
git worktree lock ../feature-x
git worktree lock --reason "On USB drive" ../feature-x

# Unlock worktree
git worktree unlock ../feature-x
古いワークツリーを整理
# Remove stale worktree metadata (after manual directory deletion)
git worktree prune

# Dry-run to see what would be pruned
git worktree prune --dry-run

# Verbose output
git worktree prune -v
ワークツリーを修復
# Repair worktree links after moving directories manually
git worktree repair

# Repair specific worktree
git worktree repair ../feature-x

ワークフローのパターン

パターン1：機能開発とホットフィックスを並行して行う

機能開発を進めながらバグを修正するには：

# Create worktree for hotfix from main
git worktree add -b hotfix-456 ../project-hotfix origin/main

# Switch to hotfix directory, fix, commit, push
cd ../project-hotfix
git add . && git commit -m "fix: resolve critical bug #456"
git push origin hotfix-456

# Return to feature work
cd ../project

# Clean up when done
git worktree remove ../project-hotfix
パターン2：作業中にプルリクエストをレビューする

現在の作業に影響を与えずにプルリクエストをレビューするには：

# Fetch PR branch and create worktree
git fetch origin pull/123/head:pr-123
git worktree add ../project-review pr-123

# Review: run tests, inspect code
cd ../project-review

# Return to work, then clean up
cd ../project
git worktree remove ../project-review
git branch -d pr-123
パターン3：実装を比較する

ブランチ間のコードを並べて比較するには：

# Create worktrees for different versions
git worktree add ../project-v1 v1.0.0
git worktree add ../project-v2 v2.0.0

# Diff, compare, or run both simultaneously
diff ../project-v1/src/module.js ../project-v2/src/module.js

# Clean up
git worktree remove ../project-v1
git worktree remove ../project-v2
パターン4：長時間実行するタスク

開発を続けながら、テストやビルドを分離して実行するには：

# Create worktree for CI-like testing
git worktree add ../project-test main

# Start long-running tests in background
cd ../project-test && npm test &

# Continue development in main worktree
cd ../project
パターン5：安定した参照先

参照用に、クリーンなメインチェックアウトを維持するには：

# Create permanent worktree for main branch
git worktree add ../project-main main

# Lock to prevent accidental removal
git worktree lock --reason "Reference checkout" ../project-main
パターン6：複数の機能ブランチから選択的にマージする

複数の機能ブランチから特定の変更を組み合わせるには：

# Create worktrees for each feature to review
git worktree add ../project-feature-1 feature-1
git worktree add ../project-feature-2 feature-2

# Review changes in each worktree
diff ../project/src/module.js ../project-feature-1/src/module.js
diff ../project/src/module.js ../project-feature-2/src/module.js

# From main worktree, selectively take changes
cd ../project
git checkout feature-1 -- src/moduleA.js src/utils.js
git checkout feature-2 -- src/moduleB.js
git commit -m "feat: combine selected changes from feature branches"

# Or cherry-pick specific commits
git cherry-pick abc1234  # from feature-1
git cherry-pick def5678  # from feature-2

# Clean up
git worktree remove ../project-feature-1
git worktree remove ../project-feature-2

ワークツリー間の変更を比較・マージする

すべてのワークツリーは同じ Git リポジトリを共有しているため、ファイルを比較したり、コミットをチェリーピックしたり、変更を選択的にマージしたりできます。

ファイルの変更を比較してレビューする

ワークツリーは単なるディレクトリなので、ファイルを直接比較できます。

# Compare specific file between worktrees
diff ../project-main/src/app.js ../project-feature/src/app.js

# Use git diff to compare branches (works from any worktree)
git diff main..feature-branch -- src/app.js

# Visual diff with your preferred tool
code --diff ../project-main/src/app.js ../project-feature/src/app.js

# Compare entire directories
diff -r ../project-v1/src ../project-v2/src
ワークツリーから1つのファイルだけをマージする

git checkout を使うと、別のブランチから単一のファイルを選択的に取り込めます。

# In your current branch, get a specific file from another branch
git checkout feature-branch -- path/to/file.js

# Or get it from a specific commit
git checkout abc1234 -- path/to/file.js

# Get multiple specific files
git checkout feature-branch -- src/module.js src/utils.js

ファイルの一部の変更（特定のハンク／行のみ）を取り込む場合：

# Interactive patch mode - select which changes to take
git checkout -p feature-branch -- path/to/file.js

次のオプションを使って、変更の各ハンクを個別に適用するかどうかを選択するプロンプトが表示されます：

  • y - このハンクを適用
  • n - このハンクをスキップ
  • s - より小さなハンクに分割
  • e - ハンクを手動で編集
ワークツリーからコミットをチェリーピックする

チェリーピックはコミット単位で行われます。すべてのワークツリーは同じリポジトリを共有しているため、任意のコミットをチェリーピックできます。

# Find the commit hash (from any worktree or git log)
git log feature-branch --oneline

# Cherry-pick specific commit into your current branch
git cherry-pick abc1234

# Cherry-pick multiple commits
git cherry-pick abc1234 def5678

# Cherry-pick a range of commits
git cherry-pick abc1234^..def5678

# Cherry-pick without committing (stage changes only)
git cherry-pick --no-commit abc1234
複数のワークツリーから変更をマージする

複数のブランチからマージまたはチェリーピックできます。

# Merge multiple branches sequentially
git merge feature-1
git merge feature-2

# Or use octopus merge for multiple branches at once
git merge feature-1 feature-2 feature-3

# Cherry-pick commits from multiple branches
git cherry-pick abc1234  # from feature-1
git cherry-pick def5678  # from feature-2
選択的なマージ - 取り込む変更を選択する
オプション 1：選択的なファイルのチェックアウト
# Get specific files from different branches
git checkout feature-1 -- src/moduleA.js
git checkout feature-2 -- src/moduleB.js
git commit -m "Merge selected files from feature branches"
オプション 2：対話的なパッチの選択
# Select specific hunks from a file
git checkout -p feature-1 -- src/shared.js
オプション 3：選択的なステージングでチェリーピックする
# Apply changes without committing
git cherry-pick --no-commit abc1234

# Unstage what you don't want
git reset HEAD -- unwanted-file.js
git checkout -- unwanted-file.js

# Commit only what you kept
git commit -m "Selected changes from feature-1"
オプション 4：手動選択でマージする
# Start merge but don't auto-commit
git merge --no-commit feature-1

# Review and modify staged changes
git status
git reset HEAD -- file-to-exclude.js
git checkout -- file-to-exclude.js

# Commit your selection
git commit -m "Merge selected changes from feature-1"
オプション 5：git restore を使用する（Git 2.23+）
# Restore specific file from another branch
git restore --source=feature-branch -- path/to/file.js

# Interactive restore with patch selection
git restore -p --source=feature-branch -- path/to/file.js

ディレクトリ構成の慣例

作業ツリーを予測しやすいように整理します。

~/projects/
  myproject/              # Main worktree (main/master branch)
  myproject-feature-x/    # Feature branch worktree
  myproject-hotfix/       # Hotfix worktree
  myproject-review/       # Temporary PR review worktree

命名規則： <project>-<purpose> または <project>-<branch>

ベストプラクティス

プラクティス理由
兄弟ディレクトリを使用する移動しやすいように、作業ツリーをメインプロジェクトと同じ階層に配置します
目的に基づいて名前を付けるproject-review は project-pr-123 よりも分かりやすい名前です
速やかにクリーンアップする混乱を避けるため、作業が終わったら作業ツリーを削除します
リモートの作業ツリーをロックする作業ツリーがネットワーク／USB ストレージ上にある場合、プルーニングを防ぎます
実験には --detach を使用する使い捨てのブランチを作成せずに済みます
削除前にコミットするgit worktree remove の前に、必ずコミットするかスタッシュします

よくある問題と解決策

問題：「Branch is already checked out」

原因： 別の作業ツリーで使用中のブランチをチェックアウトしようとしています。

解決策：

# Find where the branch is checked out
git worktree list

# Either work in that worktree or remove it first
git worktree remove ../other-worktree
問題：手動削除後に作業ツリーが古い状態のままになる

原因： git worktree remove を使わずに作業ツリーのディレクトリを削除しました。

解決策：

# Clean up stale metadata
git worktree prune
問題：作業ツリーを手動で移動した

原因： git worktree move を使わずに作業ツリーのディレクトリを移動しました。

解決策：

# Repair the worktree links
git worktree repair
# Or specify the new path
git worktree repair /new/path/to/worktree
問題：取り外したドライブ上の作業ツリー

原因： 作業ツリーが、現在は接続されていないリムーバブルストレージ上にありました。

解決策：

# If temporary, lock it to prevent pruning
git worktree lock ../usb-worktree

# If permanent, prune it
git worktree prune

よくある間違い

間違い修正方法
作業ツリーの削除に rm -rf を使う必ず git worktree remove を使い、必要に応じて git worktree prune を実行します
ブランチが作業ツリーにロックされていることを忘れるチェックアウトエラーが発生したら git worktree list を実行します
一時的な作業ツリーをクリーンアップしないタスクの完了後、すぐに作業ツリーを削除します
入れ子の場所に作業ツリーを作成するサブディレクトリではなく、兄弟ディレクトリ（../project-feature）を使います
作業ツリーのディレクトリを手動で移動するgit worktree move を使うか、移動後に git worktree repair を実行します

エージェントのワークフローへの統合

エージェントのタスクを並行して分離するには：

# Create worktree for isolated task
git worktree add -b task-123 ../project-task-123
cd ../project-task-123
# Make changes, run tests, return
cd ../project

detached HEAD で安全に実験するには：

# Create detached worktree (no branch to clean up)
git worktree add --detach ../project-experiment
cd ../project-experiment
# Experiment, then discard or commit to new branch
git worktree remove --force ../project-experiment

確認チェックリスト

作業ツリーを使用する前に：

  • ブランチは一度に 1 つの作業ツリーでしかチェックアウトできないことを理解する
  • 作業ツリーの作成場所を把握する（兄弟ディレクトリを使用する）
  • 一時的な作業ツリーのクリーンアップ方法を計画する

作業ツリーを作成するとき：

  • 説明的なディレクトリ名を使用する
  • ブランチが別の場所ですでにチェックアウトされていないことを確認する
  • 実験には --detach の使用を検討する

作業ツリーを削除するとき：

  • 未コミットの変更をコミットするか、スタッシュする
  • rm -rf ではなく git worktree remove を使用する
  • ディレクトリを手動で削除した場合は git worktree prune を実行する

作業ツリーを比較する方法

Git の作業ツリー間でファイルやディレクトリを比較するワークフローです。ブランチや作業ツリー間でコードがどのように異なるかを把握できます。

手順

重要：以下の手順を記載どおり正確に実行してください。

  1. 現在の状態を確認する：git worktree list を実行して、既存のすべてのワークツリーとその場所を表示します

  2. ユーザー入力を解析する：指定された各引数を分類します。

    • 引数なし：対話モードです。何を比較するかユーザーに尋ねます
    • --stat：差分の概要統計（変更されたファイル、追加行、削除行）を表示します
    • ワークツリーのパス：git worktree list のワークツリーのルートと一致するパスです
    • ブランチ名：いずれかのワークツリーのブランチと一致する名前です
    • ファイル／ディレクトリのパス：現在のワークツリー内で比較するパスです

  3. 比較対象を決定する（比較するワークツリー）： a. ユーザーがワークツリーのパスを指定した場合：それらを比較対象として使用します b. ユーザーがブランチ名を指定した場合：git worktree list から該当ブランチのワークツリーを検索します c. 現在のワークツリー以外にワークツリーが1つだけある場合：現在のワークツリーとそのワークツリーを比較対象として使用します d. 複数のワークツリーがあり、指定がない場合：一覧を表示し、どれを比較するかユーザーに尋ねます e. ほかにワークツリーがない場合：git diff を使ってブランチと比較することを提案します

  4. 比較対象を決定する（ワークツリー内のファイル／ディレクトリ）： a. ユーザーがファイルまたはディレクトリのパスを指定した場合：そのすべてを比較します b. 特定のパスが指定されていない場合、ユーザーに尋ねます。

    • 「ワークツリー全体を比較しますか？」または
    • 「特定のファイル／ディレクトリを比較しますか？（パスを入力してください）」

  5. 比較を実行する：

    ワークツリー間の特定ファイルの場合：

    diff <worktree1>/<path> <worktree2>/<path>
# Or for unified diff format:
diff -u <worktree1>/<path> <worktree2>/<path>

    ワークツリー間のディレクトリの場合：

    diff -r <worktree1>/<directory> <worktree2>/<directory>
# Or for summary only:
diff -rq <worktree1>/<directory> <worktree2>/<directory>

    ブランチレベルの比較（git diff を使用）の場合：

    git diff <branch1>..<branch2> -- <path>
# Or for stat summary:
git diff --stat <branch1>..<branch2>

    現在の作業ディレクトリとの比較の場合：

    diff <current-file> <other-worktree>/<file>

  6. 結果を整形して提示する：

    • 比較対象が明確に分かる見出しを表示します
    • 差分が大きい場合は、最初に概要を表示するかどうかを確認します
    • 重要な変更（新規ファイル、削除されたファイル、名前が変更されたファイル）を強調します
    • 各ワークツリーに含まれるブランチについて説明します

比較モード

モード説明コマンドの形式
ファイル差分ワークツリー間の単一ファイルを比較しますdiff -u <wt1>/file <wt2>/file
ディレクトリ差分ディレクトリを再帰的に比較しますdiff -r <wt1>/dir <wt2>/dir
概要のみ差異のあるファイルを表示します（内容は表示しません）diff -rq <wt1>/ <wt2>/
Git 差分Git の差分機能を使用します（ブランチベース）git diff branch1..branch2 -- path
統計表示変更の統計情報を表示しますgit diff --stat branch1..branch2

ワークツリーの検出

このコマンドは git worktree list を使ってワークツリーを検出します。

/home/user/project           abc1234 [main]
/home/user/project-feature   def5678 [feature-x]
/home/user/project-hotfix    ghi9012 [hotfix-123]

この出力から、コマンドは次の情報を取得します。

  • パス：ワークツリーのディレクトリへの絶対パス
  • ブランチ：角括弧内のブランチ名（ユーザーがブランチ名を指定した場合に使用）

例

ワークツリー間の特定ファイルを比較する：

> /worktrees compare src/app.js
# Prompts to select which worktree to compare with
# Shows diff of src/app.js between current and selected worktree

2つの特定のワークツリーを比較する：

> /worktrees compare ../project-main ../project-feature src/module.js
# Compares src/module.js between the two specified worktrees

複数のファイル／ディレクトリを比較する：

> /worktrees compare src/app.js src/utils/ package.json
# Shows diffs for all three paths between worktrees

ディレクトリ全体を比較する：

> /worktrees compare src/
# Shows all differences in src/ directory between worktrees

概要統計を取得する：

> /worktrees compare --stat
# Shows which files differ and line counts

対話モード：

> /worktrees compare
# Lists available worktrees
# Asks which to compare
# Asks for specific paths or entire worktree

ブランチ名でブランチのワークツリーを比較する：

> /worktrees compare feature-x
# Finds worktree for feature-x branch and compares

ブランチのワークツリー間で特定のパスを比較する：

> /worktrees compare main feature-x src/ tests/
# Compares src/ and tests/ directories between main and feature-x worktrees

出力形式

ファイル比較の見出し：

Comparing: src/app.js
  From: /home/user/project (main)
  To:   /home/user/project-feature (feature-x)
---
[diff output]

概要出力：

Worktree Comparison Summary
===========================
From: /home/user/project (main)
To:   /home/user/project-feature (feature-x)

Files only in main:
  - src/deprecated.js

Files only in feature-x:
  + src/new-feature.js
  + src/new-feature.test.js

Files that differ:
  ~ src/app.js
  ~ src/utils/helpers.js
  ~ package.json

Statistics:
  3 files changed
  2 files added
  1 file removed

よくあるワークフロー

機能変更をレビューする
# See what changed in a feature branch
> /worktrees compare --stat
> /worktrees compare src/components/
実装を比較する
# Compare how two features implemented similar functionality
> /worktrees compare ../project-feature-1 ../project-feature-2 src/auth/
ファイルをすばやく確認する
# Check if a specific file differs
> /worktrees compare package.json
マージ前のレビュー
# Review all changes before merging (compare src and tests together)
> /worktrees compare --stat
> /worktrees compare src/ tests/
# Both src/ and tests/ directories will be compared

重要な注意事項

  • 引数の判定：コマンドは、引数を git worktree list の出力と照合して、種類を自動判定します。

    • worktree のルートに一致するパス → 比較対象の worktree として扱われます
    • worktree 内のブランチに一致する名前 → 比較対象の worktree として扱われます
    • その他のパス → worktree 内で比較するファイル／ディレクトリとして扱われます

  • 複数のパス：複数のファイル／ディレクトリのパスを指定した場合、選択した worktree 間ですべてのパスが比較されます（最初のパスだけではありません）。

  • worktree のパス：worktree を指定する場合は、絶対パスまたは現在のディレクトリからの相対パスを使用してください（例：../project-feature）。

  • ブランチと worktree：ブランチ名を指定すると、コマンドはそのブランチがチェックアウトされている worktree を探します。そのブランチの worktree がない場合は、代わりに git diff を使うよう提案します。

  • 大きな差分：大きなディレクトリの場合、完全な差分を表示する前に、まず概要を表示するかどうかを確認します。

  • バイナリファイル：バイナリファイルは検出され、実際の差分を表示せずに「Binary files differ」と報告されます。

  • ファイルのアクセス権：アクセス権に違いがある場合、差分にはその変更も表示されます。

  • worktree がない場合：他に worktree がない場合、作成方法を説明し、代わりにブランチを比較するため git diff を使うよう提案します。

worktree の作成との連携

比較用の worktree を設定するには、まず /worktrees create を使用します。

# Create worktrees for comparison
> /worktrees create feature-x, main
# Created: ../project-feature-x and ../project-main

# Now compare
> /worktrees compare src/

トラブルシューティング

「No other worktrees found」

  • まず /worktrees create <branch> で worktree を作成してください
  • または、worktree を使わずにブランチのみを比較するには git diff を使用してください

「Worktree for branch not found」

  • そのブランチの worktree が作成されていない可能性があります
  • git worktree list を実行して、利用可能な worktree を確認してください
  • /worktrees create <branch> で worktree を作成してください

「Path does not exist in worktree」

  • 指定したファイル／ディレクトリが、いずれかの worktree に存在しない可能性があります
  • これは、そのファイルが一方のブランチで追加または削除されたことを示している場合があります
  • コマンドは比較結果にこの内容を報告します

worktree の作成方法

依存関係を自動検出してインストールしながら、並行開発用の git worktree を作成、設定するワークフローです。

手順

重要：以下の手順を記載どおりに正確に実行してください。

  1. 現在の状態を確認：git worktree list を実行して既存の worktree を表示し、git status を実行してリポジトリの状態がクリーンであること（問題の原因となる未コミットの変更がないこと）を確認します。

  2. 最新のリモートブランチを取得：git fetch --all を実行し、すべてのリモートブランチをローカルで把握できるようにします。

  3. ユーザー入力を解析：ユーザーが作成するものを特定します。

    • <name>：自動検出したタイプのプレフィックスを使って worktree を作成します
    • --list：既存の worktree を表示するだけで終了します
    • 入力なし：ユーザーに名前を対話形式で尋ねます

  4. 名前からブランチタイプを自動検出：最初の単語が既知のブランチタイプかどうかを確認します。該当する場合はそれをプレフィックスとして使い、残りを名前にします。該当しない場合は、デフォルトで feature/ を使います。

    既知のタイプ： feature、feat、fix、bug、bugfix、hotfix、release、docs、test、refactor、chore、spike、experiment、review

    例：

    • refactor auth system → refactor/auth-system
    • fix login bug → fix/login-bug
    • auth system → feature/auth-system（デフォルト）
    • hotfix critical error → hotfix/critical-error

    名前の正規化： スペースをダッシュに変換し、小文字にし、ダッシュとアンダースコア以外の特殊文字を削除します。

  5. 作成する worktree ごとに実施： a. ブランチ名を構築：検出したタイプと正規化した名前から完全なブランチ名を作成します。

    • <prefix>/<normalized-name>（例：feature/auth-system）

    b. ブランチを解決：ブランチがローカルに存在するか、リモートに存在するか、新規作成が必要かを判断します。

    • ブランチがローカルに存在する場合：git worktree add ../<project>-<name> <branch>
    • ブランチがリモートに存在する場合（origin/）：git worktree add --track -b <branch> ../<project>-<name> origin/<branch>
    • ブランチが存在しない場合：ユーザーにベースブランチを尋ねます（デフォルト：現在のブランチ、または main/master）。次に git worktree add -b <branch> ../<project>-<name> <base> を実行します。

    c. パスの規則：兄弟ディレクトリを使い、../<project-name>-<name> の形式にします。

    • 現在のディレクトリからプロジェクト名を取得します
    • 正規化した名前を使います（プレフィックスを含む完全なブランチ名は使いません）
    • 例：feature/auth-system → ../myproject-auth-system

    d. worktree を作成：適切な git worktree add コマンドを実行します。

    e. 依存関係を検出：新しい worktree 内で依存関係ファイルを確認し、セットアップが必要か判断します。

    • package.json -> Node.js プロジェクト（npm/yarn/pnpm/bun）
    • requirements.txt、pyproject.toml、または setup.py -> Python プロジェクト
    • Cargo.toml -> Rust プロジェクト
    • go.mod -> Go プロジェクト
    • Gemfile -> Ruby プロジェクト
    • composer.json -> PHP プロジェクト

    f. パッケージマネージャーを検出（Node.js プロジェクトの場合）：

    • bun.lockb -> bun install を使用
    • pnpm-lock.yaml -> pnpm install を使用
    • yarn.lock -> yarn install を使用
    • package-lock.json またはデフォルト -> npm install を使用

    g. 自動セットアップ：依存関係のインストールを自動的に実行します。

    • worktree に移動して、検出したインストールコマンドを実行します
    • 進行状況を報告します：「[package manager] で依存関係をインストールしています...」
    • インストールに失敗した場合はエラーを報告しますが、worktree 作成の概要表示は続行します

  6. 概要：作成した worktree の概要を表示します。

    • worktree のパス
    • ブランチ名（プレフィックスを含む完全な名前）
    • セットアップ状況（依存関係のインストール済み、または失敗）
    • すばやく移動するコマンド：cd <worktree-path>

Worktree のパス規則

worktree は、整理しやすいよう兄弟ディレクトリとして作成します。

~/projects/
  myproject/                # Main worktree (current directory)
  myproject-add-auth/       # Feature branch worktree (feature/add-auth)
  myproject-critical-bug/   # Hotfix worktree (hotfix/critical-bug)
  myproject-pr-456/         # PR review worktree (review/pr-456)

命名規則：

  • 形式：<project-name>-<name>（ブランチ全体ではなく、名前の部分を使用します）
  • ブランチ名：<type-prefix>/<name>（例：feature/add-auth）
  • 簡潔にするため、ディレクトリ名には <name> の部分のみを使用します

例

機能用 worktree（デフォルト）：

> /worktrees create auth system
# Branch: feature/auth-system
# Creates: ../myproject-auth-system

修正用 worktree：

> /worktrees create fix login error
# Branch: fix/login-error
# Creates: ../myproject-login-error

リファクタリング用 worktree：

> /worktrees create refactor api layer
# Branch: refactor/api-layer
# Creates: ../myproject-api-layer

ホットフィックス用 worktree：

> /worktrees create hotfix critical bug
# Branch: hotfix/critical-bug
# Creates: ../myproject-critical-bug

既存の worktree の一覧表示：

> /worktrees list
# Shows: git worktree list output

セットアップ検出の例

pnpm を使用する Node.js プロジェクト：

Detected Node.js project with pnpm-lock.yaml
Installing dependencies with pnpm...
✓ Dependencies installed successfully

Python プロジェクト：

Detected Python project with requirements.txt
Installing dependencies with pip...
✓ Dependencies installed successfully

Rust プロジェクト：

Detected Rust project with Cargo.toml
Building project with cargo...
✓ Project built successfully

よくあるワークフロー

手早く機能ブランチを作成
> /worktrees create new dashboard
# Branch: feature/new-dashboard
# Creates worktree, installs dependencies, ready to code
機能の作業中にホットフィックスを適用
# In main worktree, working on feature
> /worktrees create hotfix critical bug
# Branch: hotfix/critical-bug
# Creates separate worktree from main/master
# Fix bug in hotfix worktree
# Return to feature work when done
stash を使わずに PR をレビュー
> /worktrees create review pr 123
# Branch: review/pr-123
# Creates worktree for reviewing PR
# Can run tests, inspect code
# Delete when review complete
実験または試験的な作業
> /worktrees create spike new architecture
# Branch: spike/new-architecture
# Creates isolated worktree for experimentation
# Discard or merge based on results

重要な注意事項

  • ブランチのロック：各ブランチは一度に 1 つの worktree でのみチェックアウトできます。ブランチがすでにチェックアウトされている場合、どの worktree で使用されているかがコマンドから通知されます。

  • 共有される .git：すべての worktree は同じ Git オブジェクトデータベースを共有します。いずれかの worktree でコミットした変更は、ほかのすべての worktree から確認できます。

  • クリーンな作業ディレクトリ：コマンドは未コミットの変更を確認し、存在する場合は警告します。クリーンな状態で作成するのが最も安全です。

  • 兄弟ディレクトリ：workspace を整理しておくため、worktree は必ず兄弟ディレクトリ（../ を使用）として作成されます。メインリポジトリ内に worktree を作成しないでください。

  • 依存関係の自動インストール：コマンドはプロジェクトの種類とパッケージマネージャーを自動検出し、確認を求めずに適切なインストールコマンドを実行します。

  • リモート追跡：リモートブランチの場合、worktree は適切な追跡設定（--track フラグ）を付けて作成されるため、pull と push が正しく動作します。

クリーンアップ

worktree の使用を終えたら、適切な削除コマンドを使用してください。

git worktree remove ../myproject-add-auth

未コミットの変更がある worktree の場合は、次のようにします。

git worktree remove --force ../myproject-add-auth

worktree の削除に rm -rf は使用しないでください。必ず git worktree remove を使用してください。

トラブルシューティング

「Branch is already checked out」

  • git worktree list を実行して、ブランチがどこでチェックアウトされているか確認します
  • その worktree で作業するか、先に削除してください

「Cannot create worktree - path already exists」

  • 対象のディレクトリはすでに存在しています
  • 削除するか、別の worktree のパスを選択してください

「Dependency installation failed」

  • worktree に手動で移動します：cd ../myproject-<name>
  • インストールコマンドを直接実行して、エラーの詳細を確認します
  • よくある原因：システム依存関係の不足、ネットワークの問題、ロックファイルの破損

「Wrong type detected」

  • 最初の単語が既知の種類であれば、それがブランチの種類として使用されます
  • 特定の種類を指定するには、次のいずれかを先頭に入力します：fix、hotfix、docs、test、refactor、chore、spike、review
  • 最初の単語が既知の種類でない場合、デフォルトの種類は feature/ です

Worktree のマージ方法

ユーザーが Git worktree から現在のブランチに変更をマージできるよう支援するワークフローです。ファイルの単純なチェックアウトから、変更を選択して cherry-pick する方法まで、複数のマージ戦略に対応しています。

手順

重要：以下の手順を記載どおりに正確に実行してください。

  1. 現在の状態を確認：git worktree list を実行して既存のすべての worktree を表示し、git status を実行して作業ディレクトリの状態を確認します

  2. ユーザー入力を解析：ユーザーが希望するマージ操作を判断します：

    • --interactive または引数なし：ガイド付きの対話モード
    • ファイル／ディレクトリのパス：worktree から特定のファイルまたはディレクトリをマージ
    • コミット名：特定のコミットをチェリーピック
    • ブランチ名：そのブランチの worktree からマージ
    • --from <worktree>：ソース worktree を明示的に指定
    • --patch または -p：対話型パッチ選択モードを使用

  3. ソース worktree／ブランチを決定： a. ユーザーが --from <worktree> を指定した場合：その worktree のパスを直接使用します b. ユーザーがブランチ名を指定した場合：git worktree list からそのブランチの worktree を検索します c. 他の worktree が 1 つだけ存在する場合：それをソースとして使用してよいか確認します d. 複数の worktree が存在する場合：一覧を提示し、どれからマージするかユーザーに尋ねます e. 他の worktree が存在しない場合：その旨を説明し、代わりにブランチベースのマージを提案します

  4. マージ戦略を決定：ユーザーのニーズに応じて選択肢を提示します：

    戦略 A：ファイルを選択してチェックアウト（特定のファイル／ディレクトリの場合）

    • 最適な用途：別のブランチからファイル全体を取得する
    • コマンド：git checkout <branch> -- <path>

    戦略 B：対話型パッチ選択（ファイルの一部の変更の場合）

    • 最適な用途：ファイルから特定のハンク／行を選択する
    • コマンド：git checkout -p <branch> -- <path>
    • 各ハンクについてユーザーに確認：y（適用）、n（スキップ）、s（分割）、e（編集）

    戦略 C：選択的なステージングを伴うチェリーピック（特定のコミットの場合）

    • 最適な用途：一部の変更を除外してコミットを適用する
    • 手順：
      1. git cherry-pick --no-commit <commit>
      2. ステージ済みの変更を確認します
      3. git reset HEAD -- <unwanted-files> を実行してステージングを解除します
      4. git checkout -- <unwanted-files> を実行して破棄します
      5. git commit -m "message"

    戦略 D：競合を伴う手動マージ（複雑なマージの場合）

    • 最適な用途：解決方法を制御しながらブランチ全体をマージする
    • 手順：
      1. git merge --no-commit <branch>
      2. すべての変更を確認します
      3. ファイルを選択してステージング／ステージング解除します
      4. 競合があれば解決します
      5. git commit -m "message"

    戦略 E：複数の worktree からの選択的マージ（複数のソースから組み合わせる場合）

    • 最適な用途：異なる worktree から別々のファイルを取得する
    • 手順：
      1. git checkout <branch1> -- <path1>
      2. git checkout <branch2> -- <path2>
      3. git commit -m "Merge selected files from multiple branches"

  5. 選択した戦略を実行：

    • ユーザーが確認を希望する場合は、マージ前に比較を実行します（最初に /worktrees compare を提案してください）
    • 選択した戦略の Git コマンドを実行します
    • 発生した競合に対処します
    • 最終コミットの前に変更を確認します

  6. マージ後の概要：マージ内容を表示します：

    • 変更／追加／削除されたファイル
    • ソース worktree／ブランチ
    • 使用したマージ戦略

  7. クリーンアップの確認：マージが成功した後、次のように尋ねます：

    • 「ローカルの状態を整理するために、worktree を削除しますか？」
    • はいの場合：worktree の一覧を表示し、どれを削除するか尋ねます
    • 選択された worktree に対して git worktree remove <path> を実行します
    • 必要に応じて git worktree prune を実行するよう伝えます

マージ戦略のリファレンス

戦略使用する場面コマンドの形式
ファイルを選択別のブランチからファイル全体を取得する必要があるgit checkout <branch> -- <path>
対話型パッチファイル内の特定の変更が必要git checkout -p <branch> -- <path>
選択的チェリーピックコミットは必要だが、その変更のすべては必要ないgit cherry-pick --no-commit + 選択的なステージング
手動マージ制御しながらブランチ全体をマージするgit merge --no-commit + 選択的なステージング
複数ソース複数のブランチからファイルを組み合わせる複数の git checkout <branch> -- <path>

例

worktree から単一ファイルをマージする：

> /worktrees merge src/app.js --from ../project-feature
# Prompts for merge strategy
# Executes: git checkout feature-branch -- src/app.js

対話形式でパッチを選択する：

> /worktrees merge src/utils.js --patch
# Lists available worktrees to select from
# Runs: git checkout -p feature-branch -- src/utils.js
# User selects hunks interactively (y/n/s/e)

特定のコミットをチェリーピックする：

> /worktrees merge abc1234
# Detects commit hash
# Asks: Apply entire commit or selective?
# If selective: git cherry-pick --no-commit abc1234
# Then guides through unstaging unwanted changes

ガイド付きモードをすべて実行する：

> /worktrees merge
# Lists all worktrees
# Asks what to merge (files, commits, or branches)
# Guides through appropriate strategy
# Offers cleanup at end

競合を伴うディレクトリのマージ：

> /worktrees merge src/components/ --from ../project-refactor
# Strategy D: Manual merge with conflicts
# git merge --no-commit refactor-branch
# Helps resolve any conflicts
# Reviews and commits selected changes

対話型パッチモードのガイド

--patch または Strategy B を使用すると、変更のハンクごとにプロンプトが表示されます。

@@ -10,6 +10,8 @@ function processData(input) {
   const result = transform(input);
+  // Added validation
+  if (!isValid(result)) throw new Error('Invalid');
   return result;
 }
Apply this hunk? [y,n,q,a,d,s,e,?]
キー操作
yこのハンクを適用する
nこのハンクをスキップする
q終了する（このハンクおよび残りのハンクを適用しない）
aこのハンクと残りすべてのハンクを適用する
dこのファイルのこのハンクおよび残りのハンクを適用しない
sより小さなハンクに分割する
eハンクを手動で編集する
?ヘルプを表示する

チェリーピックの選択的ワークフロー

Strategy C（選択的なステージングを伴うチェリーピック）の場合：

# 1. Apply commit without committing
git cherry-pick --no-commit abc1234

# 2. Check what was staged
git status

# 3. Unstage files you don't want
git reset HEAD -- path/to/unwanted.js

# 4. Discard changes to those files
git checkout -- path/to/unwanted.js

# 5. Commit the remaining changes
git commit -m "Cherry-pick selected changes from abc1234"

複数の worktree をマージするワークフロー

Strategy E（複数の worktree からのマージ）の場合：

# Get files from different branches
git checkout feature-auth -- src/auth/login.js src/auth/session.js
git checkout feature-api -- src/api/endpoints.js
git checkout feature-ui -- src/components/Header.js

# Review all changes
git status
git diff --cached

# Commit combined changes
git commit -m "feat: combine auth, API, and UI improvements from feature branches"

よくあるワークフロー

フルマージせずに機能ファイルを取り込む
> /worktrees merge src/new-feature.js --from ../project-feature
# Gets just the file, not the entire branch
hotfix ブランチからバグ修正の一部を取り込む
> /worktrees merge --patch src/utils.js --from ../project-hotfix
# Select only the specific bug fix hunks, not all changes
複数の PR の変更を組み合わせる
> /worktrees merge --interactive
# Select specific files from PR-1 worktree
# Select other files from PR-2 worktree
# Combine into single coherent commit
マージ前のレビュー
# First review what will be merged
> /worktrees compare src/module.js
# Then merge with confidence
> /worktrees merge src/module.js --from ../project-feature

重要な注意事項

  • 作業ディレクトリの状態：マージする前に、作業ディレクトリがクリーンであることを必ず確認してください。コミットされていない変更があると、競合が発生する可能性があります。

  • マージ前のレビュー：マージによって適用される変更を把握するために、マージ前に /worktrees compare を使用することを検討してください。

  • 競合の解決：マージ中に競合が発生した場合、コミットする前にコマンドが競合の特定と解決を支援します。

  • コミットしないフラグ：ほとんどのストラテジーでは --no-commit を使用するため、最終的なコミットメッセージと含める内容を自分で決められます。

  • 共有リポジトリ：すべての worktree で同じ Git オブジェクトデータベースを共有するため、どの worktree で作成したコミットも、他の worktree からすぐにチェリーピックできます。

  • ブランチのロック：ブランチは一度に 1 つの worktree でのみチェックアウトできます。重複した worktree を作成するのではなく、マージ操作にはブランチ名を使用してください。

マージ後のクリーンアップ

マージ後、不要になった worktree のクリーンアップを検討してください。

# List worktrees
git worktree list

# Remove specific worktree (clean state required)
git worktree remove ../project-feature

# Force remove (discards uncommitted changes)
git worktree remove --force ../project-feature

# Clean up stale worktree references
git worktree prune

各マージが成功した後、コマンドがクリーンアップについて確認し、ワークスペースを整理された状態に保てるようにします。

トラブルシューティング

「マージできません：作業ディレクトリにコミットされていない変更があります」

  • まず現在の変更をコミットするか、スタッシュしてください
  • または、マージ前に git stash を実行し、マージ後に git stash pop を実行してください

「 でマージ競合が発生しました」

  • コマンドが競合しているファイルを表示します
  • ファイルを開いて競合を解決してください（<<<<<<< マーカーを探してください）
  • 解決済みのファイルを git add <file> でステージングしてください
  • git commit で続行してください

チェリーピック時に「コミットが見つかりません」と表示される

  • コミットハッシュが正しいことを確認してください
  • いずれかの worktree で git log <branch> を実行し、コミットを確認してください
  • コミットはすべての worktree で共有されています

「チェックアウトできません：ファイルが作業ツリーに存在します」と表示される

  • ファイルにローカルの変更があります
  • まずローカルの変更をコミット、スタッシュ、または破棄してください
  • その後、マージ操作を再試行してください

「worktree のブランチが見つかりません」と表示される

  • 指定された worktree は削除されている可能性があります
  • git worktree list を実行して、現在の worktree を確認してください
  • git worktree prune を使用して、古い参照をクリーンアップしてください

他のコマンドとの連携

マージ前のレビュー：

> /worktrees compare src/
> /worktrees merge src/specific-file.js

worktree を作成してマージし、クリーンアップする：

> /worktrees create feature-branch
> /worktrees compare src/
> /worktrees merge src/module.js --from ../project-feature-branch
# After merge, cleanup is offered automatically

コメント

Markdown 対応