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 の前に、必ずコミットするかスタッシュします

よくある問題と解決策

問題：「ブランチはすでにチェックアウトされています」

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

解決策：

# 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 を実行する