using-git-worktrees

tmux 統合による Git Worktree

分離されたワークスペースを作成し、現在のセッション内の tmux ウィンドウで開いて、タスクを割り当てます。すべてをひと続きのフローで実行できます。

基本フロー

1. Create worktree     → git worktree add .claude/worktrees/{name} -b {branch}
2. Create tmux window  → new window in CURRENT session named {session}-{name}
3. cd into worktree    → send-keys to the new window
4. Dispatch task       → send-keys with the command to execute

ワークフローの振り分け

意図	アクション
"create worktree for X"	作成 → ステップ 1〜3 のみ
"create worktree and run Y"	作成＋割り当て → ステップ 1〜4
"clean up worktree X"	クリーンアップ → worktree と tmux ウィンドウを削除し、必要に応じてブランチも削除
"list worktrees"	git worktree list を表示
"analyze for parallelization"	BMAD 固有の依存関係分析については references/bmad-orchestration.md を読む
"merge worktree branches"	マージのワークフローについては references/bmad-orchestration.md を読む

ステップ 1：Worktree の作成

安全性の確認

作成する前に、.claude/worktrees/ が git の追跡対象から除外されていることを確認します。

# Check if ignored (test with a hypothetical file)
git check-ignore .claude/worktrees/test 2>/dev/null

除外されていない場合は、すぐに .gitignore に追加します。

echo ".claude/worktrees/" >> .gitignore
# Stage and commit the gitignore change

作成

REPO_ROOT=$(git rev-parse --show-toplevel)
WORKTREE_NAME="the-feature-name"
BRANCH_NAME="feature/the-feature-name"  # or bmad/story-1-3 etc.
BASE_BRANCH="main"  # or current branch

mkdir -p "$REPO_ROOT/.claude/worktrees"
git worktree add "$REPO_ROOT/.claude/worktrees/$WORKTREE_NAME" -b "$BRANCH_NAME" "$BASE_BRANCH"

確認

git worktree list

ステップ 2：tmux ウィンドウの作成

新しいセッションではなく、現在の tmux セッションに新しいウィンドウを作成します。ウィンドウ名は {current-session-name}-{worktree-name} の形式にして、識別しやすくします。

# Get current tmux session name
SESSION=$(tmux display-message -p '#S')
WINDOW_NAME="${SESSION}-${WORKTREE_NAME}"
WORKTREE_PATH="$REPO_ROOT/.claude/worktrees/$WORKTREE_NAME"

# Create window in current session, starting in worktree directory
tmux new-window -t "$SESSION" -n "$WINDOW_NAME" -c "$WORKTREE_PATH"

ステップ 3：作業ディレクトリの確認

ステップ 2 の -c フラグで初期ディレクトリはすでに設定されていますが、明示的に cd する必要がある場合（例：シェルプロファイルによって設定が上書きされる場合）は、次のようにします。

tmux send-keys -t "${SESSION}:${WINDOW_NAME}" "cd '$WORKTREE_PATH'" Enter

ステップ 4：タスクの割り当て（任意）

新しい tmux ウィンドウにコマンドを送信します。

# Example: launch Claude Code with a task
tmux send-keys -t "${SESSION}:${WINDOW_NAME}" "claude 'your task here'" Enter

# Example: run a BMAD skill
tmux send-keys -t "${SESSION}:${WINDOW_NAME}" "claude '/bmad-create-story story 1-3'" Enter

# Example: run any shell command
tmux send-keys -t "${SESSION}:${WINDOW_NAME}" "make test" Enter

無人実行（権限確認なし）の場合：

tmux send-keys -t "${SESSION}:${WINDOW_NAME}" "claude --dangerously-skip-permissions 'your task'" Enter

重要： --dangerously-skip-permissions を使用するのは、ユーザーが明示的に要求した場合のみにしてください。

クリーンアップのワークフロー

作業が完了し、マージされたら：

WORKTREE_NAME="the-feature-name"
REPO_ROOT=$(git rev-parse --show-toplevel)
SESSION=$(tmux display-message -p '#S')

# 1. Kill the tmux window
tmux kill-window -t "${SESSION}:${SESSION}-${WORKTREE_NAME}" 2>/dev/null

# 2. Remove the git worktree
git worktree remove "$REPO_ROOT/.claude/worktrees/$WORKTREE_NAME"

# 3. Optionally delete the branch (only if merged)
git branch -d "$BRANCH_NAME" 2>/dev/null

# 4. Prune stale worktree references
git worktree prune

クイックリファレンス

状況	アクション
.claude/worktrees/ が存在する	使用する（除外されていることを確認）
.gitignore に含まれていない	.claude/worktrees/ を追加してコミットする
tmux 内にいない	tmux のステップを省略し、worktree を作成してパスを報告する
ブランチがすでに存在する	git worktree add <path> <existing-branch> を使用する（-b は付けない）
Worktree のパスが存在する	エラーを報告し、ユーザーに削除するか別の名前を選ぶよう依頼する

命名規則

要素	形式	例
Worktree ディレクトリ	.claude/worktrees/{name}	.claude/worktrees/story-1-3
ブランチ	{convention}/{name}	bmad/story-1-3-deploy-nat-gateway
tmux ウィンドウ	{session}-{name}	myproject-golden-image-story-1-3

ブランチの命名規則はプロジェクトによって異なります。プロジェクト固有の形式（例：BMAD プロジェクトの bmad/story-{id}）については CLAUDE.md を確認してください。

トラブルシューティング

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

# Another worktree has this branch — remove it first or use a different name
git worktree list  # find which worktree has the branch

tmux ウィンドウ名が競合しています：

# Rename or kill the conflicting window
tmux kill-window -t "session:conflicting-name" 2>/dev/null

追加後も Worktree が .gitignore に含まれていません：

# .gitignore uses directory patterns — ensure trailing slash
# Check with: git check-ignore .claude/worktrees/testfile

参考資料

• WORKFLOW.md — エッジケースを含む、詳細なステップごとのワークフロー
• references/bmad-orchestration.md — BMAD スプリントの並列化、依存関係分析、マージのワークフロー
• references/tmux-integration.md — Worktree 向けの高度な tmux 設定
• scripts/setup-worktree.sh — Worktree を自動で設定するシェルスクリプト

---

注意点

• .claude/worktrees/ は .gitignore のデフォルト設定と競合します — 明示的に除外しないと、親リポジトリで worktree 内のファイルが未追跡として表示されます。
• Worktree のパスを含む tmux セッション名はファイル名の長さ制限に達することがあります — 短いブランチベースの名前を使うか、ソケットパスでエラーが発生します。
• Worktree 間で同時に git status を実行すると、index.lock エラーが発生することがあります — git は worktree ごとではなく、リポジトリごとにインデックスをロックします。
• BMAD 固有の並列作業では、ファイルが重複しないことを前提としています：ストーリー間で編集が重複すると、統合時にマージが複雑になります。
• Worktree のパスから git ブランチを読み取るシェルプロンプトは遅くなることがあります — Worktree では、コストの高いプロンプト要素を無効にしてください。