git-worktrees

Git Worktrees

概要

Git worktree を使うと、同じリポジトリから複数の作業ディレクトリを作成し、それぞれで異なるブランチをチェックアウトできます。ブランチを切り替えずに、複数のブランチで同時に作業できます。

Worktree を使う場面

✅ 特におすすめの用途：

• 積み重ねた PR の開発（PR ごとに 1 つの worktree）
• 機能開発中に緊急のホットフィックスを適用する
• 複数の機能を並行して開発する
• 分離された環境でコードレビューを行う
• ブランチをまたいだ相互作用をテストする
• 複数の開発サーバーを同時に実行する

⚠️ 次の場合は代替手段を検討してください：

• ディスク容量が限られている（worktree は作業ディレクトリを複製します）
• 単純なブランチ切り替えで十分な場合
• 一度に 1 つのブランチだけで作業する場合

基本的なワークフロー

Worktree を作成する

新しいブランチ：

# Create worktree with new branch
git worktree add ../worktrees/feature-auth -b feature/authentication

# Navigate to worktree
cd ../worktrees/feature-auth

既存のブランチ：

# Create worktree from existing remote branch
git worktree add ../worktrees/feature-profile feature/user-profile

# Or from origin
git worktree add ../worktrees/review origin/feature/pr-to-review

Worktree を一覧表示する

git worktree list

# Output:
# /Users/dev/project              abc123 [main]
# /Users/dev/worktrees/f-auth     def456 [feature/authentication]
# /Users/dev/worktrees/f-profile  ghi789 [feature/user-profile]

Worktree を削除する

# Remove worktree (deletes directory)
git worktree remove ../worktrees/feature-auth

# Or manually delete directory and prune
rm -rf ../worktrees/feature-auth
git worktree prune

ディレクトリ構造

推奨する構成：

/Users/dev/
├── my-project/              # Main repository
│   ├── .git/               # Git database
│   ├── src/
│   └── ...
└── my-project-worktrees/    # All worktrees here
    ├── feature-auth/       # feature/authentication branch
    ├── feature-profile/    # feature/user-profile branch
    ├── hotfix-urgent/      # hotfix/urgent-fix branch
    └── review-pr-123/      # Reviewing PR #123

ユースケース：積み重ねた PR

積み重ねた PR のワークフローに最適です。PR ごとに 1 つの worktree を用意します：

# Create worktree for each PR in stack
git worktree add ../stack/pr-001 -b feature/001-base-auth
git worktree add ../stack/pr-002 -b feature/002-user-profile
git worktree add ../stack/pr-003 -b feature/003-admin-panel

# Work in each independently
cd ../stack/pr-001
# Implement base auth
git commit -am "feat: base authentication"
git push -u origin feature/001-base-auth

cd ../stack/pr-002
# Already on feature/002-user-profile branch
# Implement user profile (depends on pr-001)
git commit -am "feat: user profile with auth"
git push -u origin feature/002-user-profile

cd ../stack/pr-003
# Implement admin panel (depends on pr-002)
git commit -am "feat: admin panel"
git push -u origin feature/003-admin-panel

ユースケース：並行開発

複数の開発サーバーを同時に実行します：

# Terminal 1: Main feature development
cd /project-worktrees/feature-new-ui
npm install
npm run dev  # Server on port 3000

# Terminal 2: Urgent hotfix (different branch)
cd /project-worktrees/hotfix-critical
npm install
npm run dev -- --port 3001  # Server on port 3001

# Both running simultaneously without branch switching

ユースケース：コードレビュー

分離された環境で PR をレビューします：

# Create worktree for PR review
git worktree add ../review/pr-456 origin/feature/user-auth

cd ../review/pr-456
npm install
npm test
npm run dev

# Review code, test functionality
# When done, remove worktree
cd /main-project
git worktree remove ../review/pr-456

Worktree を使って積み重ねた PR を更新する

ベース PR が変更されたら、worktree 間でチェーンを更新します：

# PR-001 got feedback
cd /stack/pr-001
git pull origin feature/001-base-auth
# Make changes, push

# Update PR-002 (in separate worktree)
cd /stack/pr-002
git rebase feature/001-base-auth
git push --force-with-lease origin feature/002-user-profile

# Update PR-003 (in separate worktree)
cd /stack/pr-003
git rebase feature/002-user-profile
git push --force-with-lease origin feature/003-admin-panel

依存関係の管理

node_modules を共有する（ディスク容量を節約）

オプション 1：シンボリックリンク

cd /worktrees/feature-auth
ln -s /main-project/node_modules node_modules

オプション 2：個別にインストール

cd /worktrees/feature-auth
npm install  # Independent node_modules

トレードオフ：

• シンボリックリンク：ディスク容量を節約できますが、バージョンの競合が発生する場合があります
• 個別にインストール：ディスク容量を多く使いますが、確実に分離できます

ベストプラクティス

1. 命名規則

# Use descriptive, consistent names
git worktree add ../worktrees/feature-authentication feature/authentication
git worktree add ../worktrees/hotfix-security hotfix/security-patch

2. 配置場所の方針

# Keep worktrees outside main repo
/Users/dev/project/              # Main repo (never delete)
/Users/dev/project-worktrees/    # All worktrees here (safe to delete)

3. クリーンアップの徹底

# When PR merged, remove worktree immediately
git worktree remove path/to/worktree

# Periodically check for stale worktrees
git worktree prune

# Delete merged branches
git branch -d feature/old-branch
git push origin --delete feature/old-branch

4. Worktree ごとに 1 つのブランチ

❌ WRONG: Switching branches in worktree defeats the purpose
✅ CORRECT: Each worktree permanently on one branch

よく使うコマンド

# Create worktree with new branch
git worktree add <path> -b <branch>

# Create worktree from existing branch
git worktree add <path> <branch>

# List all worktrees
git worktree list

# Remove worktree
git worktree remove <path>

# Clean up stale references
git worktree prune

# Move worktree to different location
git worktree move <old-path> <new-path>

トラブルシューティング

問題："fatal: '' is already checked out"

原因： ブランチが別の worktree でチェックアウトされています

解決方法：

# List worktrees to find where branch is checked out
git worktree list

# Either work in existing worktree or remove it first
git worktree remove <path-to-old-worktree>

問題：ディスク容量が不足する

解決方法：

• node_modules にシンボリックリンクを使用する
• PR がマージされたら worktree を削除する
• 定期的に git worktree prune を実行する
• 大規模なリポジトリでは sparse-checkout の使用を検討する

問題：複数の worktree が原因で IDE が混乱する

解決方法：

• 各 worktree を個別のワークスペースとして開く
• IDE のマルチウィンドウ／ワークスペース分割機能を使う
• worktree に分かりやすい名前を付けて識別しやすくする

エージェントへの指示

バージョン管理エージェントに worktree のセットアップを委任する場合：

Task: Create worktrees for stacked PR development

Requirements:
- Create 3 worktrees in /project-worktrees/
- Worktree 1: pr-001 with branch feature/001-base-auth
- Worktree 2: pr-002 with branch feature/002-user-profile
- Worktree 3: pr-003 with branch feature/003-admin-panel

Commands:
git worktree add ../project-worktrees/pr-001 -b feature/001-base-auth
git worktree add ../project-worktrees/pr-002 -b feature/002-user-profile
git worktree add ../project-worktrees/pr-003 -b feature/003-admin-panel

Verification: git worktree list should show all 3 worktrees

メリット

✅ ブランチ切り替え不要： git checkout を使わずに複数のブランチで作業できます ✅ サーバーを並行実行： 複数の開発環境を同時に実行できます ✅ 状態を保持： ビルド成果物と node_modules はブランチごとに保持されます ✅ より安全なレビュー： メインの作業ディレクトリに影響を与えずに PR をテストできます ✅ コンテキストの切り替えを高速化： リベースする代わりに worktree 間を移動できます

関連スキル

• stacked-prs - worktree を積み重ねた PR のワークフローと組み合わせる
• git-workflow - Git の一般的なブランチ運用パターン
• code-review - 分離された worktree でコードをレビューする