worktree

Git Worktree マネージャー

git worktree を使って、複数のブランチで同時に作業できます。

前提条件

# Git 2.5+ (worktrees built-in)
git --version

CLI リファレンス

Worktree の一覧表示

# List all worktrees
git worktree list

# Porcelain format (machine-readable)
git worktree list --porcelain

Worktree の作成

# Create from existing branch
git worktree add ../feature-branch feature-branch

# Create new branch
git worktree add -b new-feature ../new-feature main

# Specific path
git worktree add /path/to/worktree branch-name

# Detached HEAD at commit
git worktree add --detach ../temp abc123

Worktree の削除

# Remove worktree
git worktree remove ../feature-branch

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

# Prune stale worktrees
git worktree prune

Worktree の操作

# Move worktree
git worktree move ../old-path ../new-path

# Lock worktree (prevent pruning)
git worktree lock ../feature-branch
git worktree lock --reason "long-running task" ../feature-branch

# Unlock
git worktree unlock ../feature-branch

ワークフローのパターン

並行した機能開発

# Main repo working on feature-a
cd ~/repos/myproject
git checkout feature-a

# Create worktree for feature-b
git worktree add ../myproject-feature-b feature-b

# Now you have two checkouts:
# ~/repos/myproject (feature-a)
# ~/repos/myproject-feature-b (feature-b)

迅速なバグ修正

# Currently working on feature
cd ~/repos/myproject

# Create worktree for hotfix
git worktree add ../myproject-hotfix -b hotfix/urgent main

# Fix bug in worktree
cd ../myproject-hotfix
# make changes
git commit -am "fix: urgent bug"
git push origin hotfix/urgent

# Create PR
gh pr create --base main --title "Hotfix: urgent bug"

# Clean up
cd ../myproject
git worktree remove ../myproject-hotfix

PR のレビュー

# Create worktree for PR branch
git fetch origin pull/123/head:pr-123
git worktree add ../myproject-pr-123 pr-123

# Review and test
cd ../myproject-pr-123
npm install
npm test

# Clean up after review
cd ../myproject
git worktree remove ../myproject-pr-123
git branch -D pr-123

長期的な比較

# Worktree for baseline
git worktree add ../myproject-baseline main

# Run tests on both
cd ~/repos/myproject
npm test > /tmp/feature-tests.log

cd ../myproject-baseline
npm test > /tmp/baseline-tests.log

diff /tmp/baseline-tests.log /tmp/feature-tests.log

ディレクトリ構成

推奨されるレイアウト：

~/repos/
├── myproject/           # Main worktree (main branch)
├── myproject-feature-a/ # Feature worktree
├── myproject-feature-b/ # Another feature
└── myproject-hotfix/    # Hotfix worktree

またはネストした構成：

~/repos/myproject/
├── main/      # Main worktree
├── features/
│   ├── auth/  # Feature worktree
│   └── ui/    # Feature worktree
└── hotfix/    # Hotfix worktree

Worktree での Beads の使用

Worktree で Beads（タスクトラッカー）を使用する場合は、デーモンを無効にします。

# In shell config
export BEADS_NO_DAEMON=1

# Or per-command
bd --no-daemon ready
bd --no-daemon create "task"

よくある問題

ブランチがすでにチェックアウトされている

# Error: 'branch' is already checked out at '/path'
# Solution: Use different branch or remove other worktree
git worktree remove /path/to/other

古い Worktree の参照

# Clean up deleted worktrees
git worktree prune

# Verbose output
git worktree prune --verbose

共有リソース

各 Worktree で共有されるもの：

• .git ディレクトリ（参照、オブジェクト）
• リモート設定
• フック

各 Worktree で個別に管理されるもの：

• 作業ディレクトリ
• インデックス（ステージング領域）
• HEAD

スクリプト

機能開発用 Worktree の作成

#!/bin/bash
FEATURE=$1
BASE=${2:-main}

git worktree add -b feature/$FEATURE ../${PWD##*/}-$FEATURE $BASE
cd ../${PWD##*/}-$FEATURE
npm install
echo "Worktree created at $(pwd)"

古い Worktree のクリーンアップ

#!/bin/bash
# Remove worktrees for merged branches

for wt in $(git worktree list --porcelain | grep "^worktree" | cut -d' ' -f2); do
  branch=$(git -C "$wt" branch --show-current)
  if git branch --merged main | grep -q "$branch"; then
    echo "Removing merged worktree: $wt ($branch)"
    git worktree remove "$wt"
  fi
done
git worktree prune

ベストプラクティス

1. わかりやすいパスを使用する - ディレクトリ名にブランチ名を含めます
2. 依存関係をインストールする - 各 Worktree で npm/yarn install を実行します
3. 定期的にプルーニングする - 古い参照をクリーンアップします
4. Worktree をネストしない - 同じ階層のディレクトリに配置します
5. 長時間実行する場合はロックする - 誤ってプルーニングされるのを防ぎます
6. IDE のワークスペースを分ける - 各 Worktree で専用の IDE ウィンドウを使います
7. Beads のデーモンを無効にする - データベースの競合を防ぎます