Git Worktree 並行開発ワークフロー完全ガイド｜複数ブランチ同時作業・IDE設定・CI連携（2026）

なぜ git worktree なのか — 並行開発の課題

フルスタック開発では、1 つの作業ディレクトリに次の要求が同時に降りてくる。

1. feature 開発 — feature/oauth-pkce で dev サーバーと DB マイグレーションを走らせている
2. hotfix — 本番障害で main から hotfix/rate-limit を切り、即デプロイが必要
3. PR レビュー — 同僚の feature/webhook-retry をローカルで再現したい
4. CI 修正 — OpenAPI spec validation CI pipeline の Spectral ルール違反を直しつつ、別 feature の実装も止めたくない

従来の対処は git stash push -u → git switch hotfix/... → 修正 → git switch - → git stash pop だ。このサイクルには次のコストが乗る。

操作	典型コスト
git switch	未コミット変更の競合、大規模 repo では index 更新に数秒
stash pop	コンフリクト解消、node_modules との不整合
dev サーバー再起動	Vite / Next.js の HMR キャッシュクリア、30秒〜2分
DB マイグレーション	feature 用スキーマと hotfix 用スキーマの食い違い
エディタの Git 状態	LSP・型チェックが別ブランチのファイルを参照

git worktree は .git オブジェクト DB を共有しつつ、ワーキングツリーだけを別パスに複製する。ブランチ A のディレクトリで npm run dev を走らせたまま、ブランチ B のディレクトリでテストを実行できる。

git worktree の仕組み

通常の clone は 1 つの working tree と 1 つの .git（ディレクトリまたはファイル）で構成される。git worktree add を実行すると、Git は次を行う。

1. 新しいディレクトリを作成（または指定パスを使用）
2. そのディレクトリに administrative files（.git ファイルで本体を指す）を配置
3. 指定ブランチを checkout（新規ブランチなら -b で作成）

すべての worktree は 同一の object database（コミット・blob・tree）を参照する。git fetch 1 回で全 worktree に新しいコミットが見える。.git/objects の重複はないため、clone を 3 回するよりディスク効率が良い。

~/dev/myapp/                 ← main worktree (branch: main)
~/dev/myapp-feature-auth/    ← linked worktree (branch: feature/auth)
~/dev/myapp-hotfix-429/      ← linked worktree (branch: hotfix/429-headers)
         │
         └── すべて ~/.git または myapp/.git/worktrees/* 経由で同一 DB

worktree と clone 3 回の比較

方式	.git オブジェクト	fetch 回数	ブランチ同時 checkout
clone × 3	3 倍	3 回	可能
worktree × 3	1 倍（共有）	1 回	可能
submodule	別 repo	別管理	別問題

monorepo で 5GB 超の .git があるプロジェクトほど、worktree の恩恵が大きい。

基本コマンド — add / list / remove / prune

初回セットアップと一覧

メイン clone のルートで作業する。すでに別ブランチにいる場合も、worktree コマンド自体は main から実行するのが分かりやすい。

# リポジトリルートへ移動
cd ~/dev/portfolio

# 現在の worktree 一覧（最初は 1 行だけ）
git worktree list --porcelain

# 人間可読形式
git worktree list
# /home/user/dev/portfolio          abc1234 [main]

feature ブランチ用 worktree を追加

# 新規ブランチ feature/openapi-spectral を作成し、兄弟ディレクトリに checkout
git worktree add ../portfolio-feature-openapi -b feature/openapi-spectral

# 既存のリモート追跡ブランチを checkout する場合
git fetch origin feature/webhook-retry
git worktree add ../portfolio-webhook-retry feature/webhook-retry

# main から hotfix 用（detached ではなくブランチ作成）
git worktree add ../portfolio-hotfix-429 -b hotfix/rate-limit-headers origin/main

パスは リポジトリ外の絶対パス でも 相対パス でもよい。チームで ~/dev/<repo>-<branch-slug>/ と命名規則を統一すると、IDE workspace 生成が楽になる。

作業終了と削除

# worktree 内で未マージ変更がないことを確認してから
cd ~/dev/portfolio-feature-openapi
git status

# 親 repo またはどこからでも remove 可能
git worktree remove ../portfolio-feature-openapi

# マージ済みブランチの削除
git branch -d feature/openapi-spectral

# 参照切れ worktree の admin ファイルを掃除
git worktree prune -v

remove 時に未コミット変更があると拒否される。 --force は本当に捨てていい場合だけ使う。

# 危険: 未コミット変更を破棄して強制削除
git worktree remove --force ../portfolio-feature-openapi

PR レビュー専用 worktree

リモート PR をローカルブランチに載せる定番パターン。

PR_NUMBER=842
git fetch origin pull/${PR_NUMBER}/head:review/pr-${PR_NUMBER}
git worktree add ../portfolio-review-pr-${PR_NUMBER} review/pr-${PR_NUMBER}

# レビュー完了後
git worktree remove ../portfolio-review-pr-${PR_NUMBER}
git branch -D review/pr-${PR_NUMBER}

実務ワークフロー — 3 つの典型パターン

パターン A: Feature 開発中の Hotfix

[main worktree]     branch: main          → 通常は最新 pull のみ、直接 commit しない
[feature worktree]  branch: feature/x     → 長期開発、dev サーバー常時起動
[hotfix worktree]   branch: hotfix/y      → 短命、マージ後即 remove

hotfix を main に merge したら、feature worktree で git merge origin/main または git rebase origin/main して取り込む。feature 側の dev サーバーは再起動不要（merge 時点でファイルが変わるだけ）。

パターン B: OpenAPI spec とアプリの二刀流

API チームでは spec-first 開発が増えている。OpenAPI 3.1 の CI パイプライン 記事で述べた validate → lint → diff の 3 段階は、PR ごとに必ず走る。

worktree	ブランチ	担当
../app-feature-orders	feature/orders-api	コントローラ・DTO 実装
../openapi-spectral-fix	chore/spectral-429-rule	.spectral.yaml と openapi.yaml 修正
../portfolio (main)	main	リリースタグ・CHANGELOG のみ

spec 修正ブランチで npm run openapi:lint が通ったら merge。アプリ feature は openapi の main 取り込み後に Schemathesis で契約テスト——worktree 分離により lint 試行錯誤の commit 履歴 がアプリ PR に混ざらない。

パターン C: 長期 feature と短期レビューの共存

レビュー用 worktree は detached HEAD 禁止（レビュー中に commit して push する「suggested change」運用ならブランチ必須）。1 PR 1 worktree、マージまたは close で remove が鉄則。

ディレクトリ命名とチーム規約

属人化を防ぐため、次の規約を README か CONTRIBUTING.md に書いておく。

要素	推奨
ベースパス	~/dev/ または repo 親ディレクトリ
命名	<repo>-<type>-<slug> 例: portfolio-feature-auth
type	feature / hotfix / review / chore
最大数	同時 5 個まで、週次で prune
env ファイル	各 worktree に .env.local をコピー（シンボリックリンクはパス事故に注意）

一括セットアップシェル（macOS / Linux）

チーム共有用の scripts/worktree-add.sh 例。5 つ目以降のフルシェルブロックとしてそのまま使える完全版。

#!/usr/bin/env bash
set -euo pipefail

REPO_ROOT="$(git rev-parse --show-toplevel)"
REPO_NAME="$(basename "${REPO_ROOT}")"
DEV_ROOT="${DEV_ROOT:-$(dirname "${REPO_ROOT}")}"

usage() {
  echo "Usage: $0 <type> <slug> [base-branch]"
  echo "  type: feature|hotfix|chore|review"
  echo "  slug: branch slug e.g. oauth-pkce"
  echo "  base-branch: optional, default main"
  exit 1
}

[[ $# -lt 2 ]] && usage

TYPE="$1"
SLUG="$2"
BASE_BRANCH="${3:-main}"
BRANCH_NAME="${TYPE}/${SLUG}"
WORKTREE_PATH="${DEV_ROOT}/${REPO_NAME}-${TYPE}-${SLUG}"

if [[ -d "${WORKTREE_PATH}" ]]; then
  echo "Error: path already exists: ${WORKTREE_PATH}" >&2
  exit 1
fi

cd "${REPO_ROOT}"
git fetch origin "${BASE_BRANCH}"

if git show-ref --verify --quiet "refs/heads/${BRANCH_NAME}"; then
  git worktree add "${WORKTREE_PATH}" "${BRANCH_NAME}"
else
  git worktree add -b "${BRANCH_NAME}" "${WORKTREE_PATH}" "origin/${BASE_BRANCH}"
fi

if [[ -f "${REPO_ROOT}/.env.example" ]] && [[ ! -f "${WORKTREE_PATH}/.env.local" ]]; then
  cp "${REPO_ROOT}/.env.example" "${WORKTREE_PATH}/.env.local"
  echo "Copied .env.example -> .env.local (edit as needed)"
fi

if [[ -f "${WORKTREE_PATH}/package.json" ]]; then
  echo "Running npm ci in new worktree..."
  (cd "${WORKTREE_PATH}" && npm ci)
fi

echo "Worktree ready: ${WORKTREE_PATH}"
echo "Branch: ${BRANCH_NAME}"
git worktree list

実行例:

chmod +x scripts/worktree-add.sh
./scripts/worktree-add.sh feature oauth-pkce main
cd ../portfolio-feature-oauth-pkce && npm run dev

Windows（PowerShell）向け worktree 操作

Windows 10/11 + Git for Windows 2.40+ では worktree は Linux 同等に動作する。パス区切りと $env:USERPROFILE に注意。

# リポジトリルート
Set-Location C:\Users\sakai\Desktop\portfolio

# worktree 一覧
git worktree list

# feature 用 worktree 追加
$WorktreePath = "C:\Users\sakai\Desktop\portfolio-feature-webhook"
$BranchName = "feature/webhook-retry"

git fetch origin main
if (git show-ref --verify --quiet "refs/heads/$BranchName") {
    git worktree add $WorktreePath $BranchName
} else {
    git worktree add -b $BranchName $WorktreePath origin/main
}

# .env コピー
$EnvExample = Join-Path (Get-Location) ".env.example"
$EnvLocal = Join-Path $WorktreePath ".env.local"
if ((Test-Path $EnvExample) -and -not (Test-Path $EnvLocal)) {
    Copy-Item $EnvExample $EnvLocal
    Write-Host "Copied .env.example to worktree"
}

# 依存関係（Node プロジェクト例）
Set-Location $WorktreePath
npm ci
npm run dev

# 削除（親 repo から実行可）
Set-Location C:\Users\sakai\Desktop\portfolio
git worktree remove $WorktreePath
git worktree prune -v

Cursor on Windows では 各 worktree を別ウィンドウ より、後述の .code-workspace マルチルートの方が WSL 混在時も安定しやすい。

IDE 設定 — Cursor / VS Code 2026

2026年時点の Cursor は VS Code 1.9x 系互換。worktree 並行開発では Multi-root Workspace が中心。

マルチルート workspace ファイル（完全例）

リポジトリルートに portfolio.code-workspace を置く。

{
  "folders": [
    {
      "name": "main",
      "path": "."
    },
    {
      "name": "feature-oauth-pkce",
      "path": "../portfolio-feature-oauth-pkce"
    },
    {
      "name": "hotfix-429",
      "path": "../portfolio-hotfix-429"
    },
    {
      "name": "review-pr-842",
      "path": "../portfolio-review-pr-842"
    }
  ],
  "settings": {
    "git.autoRepositoryDetection": "openEditors",
    "git.confirmSync": false,
    "git.enableSmartCommit": true,
    "files.exclude": {
      "**/node_modules": true,
      "**/.next": true,
      "**/dist": true
    },
    "search.exclude": {
      "**/node_modules": true,
      "**/pnpm-lock.yaml": false
    },
    "terminal.integrated.cwd": "${workspaceFolder:main}",
    "eslint.workingDirectories": [
      { "directory": ".", "changeProcessCWD": true },
      { "directory": "../portfolio-feature-oauth-pkce", "changeProcessCWD": true }
    ]
  },
  "extensions": {
    "recommendations": [
      "eamodio.gitlens",
      "github.vscode-pull-request-github",
      "redhat.vscode-yaml"
    ]
  },
  "launch": {
    "version": "0.2.0",
    "configurations": [
      {
        "name": "Dev: main",
        "type": "node",
        "request": "launch",
        "cwd": "${workspaceFolder:main}",
        "runtimeExecutable": "npm",
        "runtimeArgs": ["run", "dev"]
      },
      {
        "name": "Dev: feature-oauth",
        "type": "node",
        "request": "launch",
        "cwd": "${workspaceFolder:feature-oauth-pkce}",
        "runtimeExecutable": "npm",
        "runtimeArgs": ["run", "dev"]
      }
    ]
  }
}

Cursor で File > Open Workspace from File... から開く。Source Control パネルには フォルダごとに Git リポジトリ が表示される（実体は同一 DB）。

workspace 自動生成スクリプト

worktree を増やすたび手編集は面倒なので、Git フックまたはシェルで生成する。

#!/usr/bin/env bash
set -euo pipefail

REPO_ROOT="$(git rev-parse --show-toplevel)"
REPO_NAME="$(basename "${REPO_ROOT}")"
WORKSPACE_FILE="${REPO_ROOT}/${REPO_NAME}.code-workspace"

python3 << 'PYEOF'
import json
import subprocess
import os

repo_root = subprocess.check_output(["git", "rev-parse", "--show-toplevel"], text=True).strip()
repo_name = os.path.basename(repo_root)
workspace_file = os.path.join(repo_root, f"{repo_name}.code-workspace")

porcelain = subprocess.check_output(["git", "worktree", "list", "--porcelain"], text=True)
blocks = porcelain.strip().split("\n\n")
folders = []
for block in blocks:
    lines = block.split("\n")
    wt_path = lines[0].split(" ", 1)[1]
    branch = "detached"
    for line in lines:
        if line.startswith("branch "):
            branch = line.replace("branch refs/heads/", "")
    if os.path.normpath(wt_path) == os.path.normpath(repo_root):
        name = "main"
        rel = "."
    else:
        name = os.path.basename(wt_path).replace(f"{repo_name}-", "")
        rel = os.path.relpath(wt_path, repo_root)
    folders.append({"name": name, "path": rel})

config = {
    "folders": folders,
    "settings": {
        "git.autoRepositoryDetection": "openEditors",
        "git.repositoryScanMaxDepth": 1,
        "files.watcherExclude": {
            "**/node_modules/**": True,
            "**/.git/objects/**": True
        }
    }
}

with open(workspace_file, "w", encoding="utf-8") as f:
    json.dump(config, f, indent=2, ensure_ascii=False)
    f.write("\n")

print(f"Wrote {workspace_file} with {len(folders)} roots")
PYEOF

post-checkout や worktree add 後に手動実行する。

Cursor 固有の Tips（2026）

項目	推奨設定
Agent / Composer	ワークスペースフォルダ単位で指示。@feature-oauth-pkce フォルダを明示
ターミナル	統合ターミナルを worktree ごとに分割（タブ名を branch 名に）
GitLens	「Current worktree only」フィルタで log 混乱を防止
拡張機能	ESLint / TypeScript は eslint.workingDirectories 必須
Dev Containers	各 worktree に .devcontainer コピーは非推奨。1 repo 1 devcontainer を main に置き、worktree は attach

依存関係とディスク管理

worktree 最大のトレードオフは node_modules 等の非共有 だ。

戦略比較

node_modules サイズ監視

#!/usr/bin/env bash
set -euo pipefail

echo "=== Git worktrees ==="
git worktree list

echo ""
echo "=== Disk usage per worktree ==="
git worktree list --porcelain | while read -r line; do
  if [[ "${line}" == worktree* ]]; then
    wt_path="${line#worktree }"
    if [[ -d "${wt_path}" ]]; then
      du_sh="$(du -sh "${wt_path}" 2>/dev/null | cut -f1)"
      nm_size="N/A"
      if [[ -d "${wt_path}/node_modules" ]]; then
        nm_size="$(du -sh "${wt_path}/node_modules" 2>/dev/null | cut -f1)"
      fi
      printf "%-50s total=%-8s node_modules=%s\n" "${wt_path}" "${du_sh}" "${nm_size}"
    fi
  fi
done

週 1 回、git worktree prune と合わせて実行する。

CI / CD との関係

GitHub Actions の標準的な PR CI は ジョブごとに checkout するため、クラウド runner 上で worktree はあまり使われない。ただし次の場面では worktree が効く。

1. self-hosted runner — 巨大 monorepo で clone 30 分を避け、1 clone + worktree add で並列 job
2. ローカル CI 再現 — act や npm run openapi:ci を worktree ごとに走らせ、PR 提出前に OpenAPI CI バリデーション と同じ 3 段パイプラインを確認
3. リリース作業 — main worktree は clean 維持、release/v2.4 worktree で changelog のみ編集

ローカル pre-push フック（OpenAPI CI 連携）

.git/hooks/pre-push は全 worktree 共有。validate → lint → diff を push 前に走らせる例。

#!/usr/bin/env bash
set -euo pipefail

REPO_ROOT="$(git rev-parse --show-toplevel)"
cd "${REPO_ROOT}"

if [[ -f "package.json" ]] && grep -q '"openapi:ci"' package.json 2>/dev/null; then
  echo "[pre-push] Running OpenAPI CI (validate / lint / diff)..."
  npm run openapi:ci
  echo "[pre-push] OpenAPI CI passed."
fi

if [[ -f "package.json" ]] && grep -q '"test:ci"' package.json 2>/dev/null; then
  echo "[pre-push] Running test:ci..."
  npm run test:ci
fi

exit 0

OpenAPI 専用 worktree では openapi/ だけを編集し、push 前に npm run openapi:lint だけ通す——といった部分実行は npm script を分けておくと効率的。Spectral カスタムルール 追加 PR では spec worktree だけで完結させ、merge 後に main の Required Check が自動的に全 PR に効く。

self-hosted runner 向け worktree 並列 build（参考）

#!/usr/bin/env bash
set -euo pipefail

CACHE_ROOT="/var/cache/git-worktrees/myapp"
REPO_URL="[email protected]:org/myapp.git"
MAIN_WT="${CACHE_ROOT}/main"

mkdir -p "${CACHE_ROOT}"

if [[ ! -d "${MAIN_WT}/.git" ]]; then
  git clone "${REPO_URL}" "${MAIN_WT}"
fi

cd "${MAIN_WT}"
git fetch origin --prune
git checkout main
git reset --hard origin/main

run_job() {
  local ref="$1"
  local job_name="$2"
  local wt_path="${CACHE_ROOT}/wt-${job_name}-$$"

  git worktree add --detach "${wt_path}" "${ref}"
  pushd "${wt_path}" >/dev/null
  npm ci --prefer-offline
  npm run "${job_name}"
  popd >/dev/null
  git worktree remove --force "${wt_path}"
}

run_job "origin/pull/842/head" "test:unit" &
run_job "origin/pull/842/head" "openapi:lint" &
wait

git worktree prune -v
echo "Parallel jobs completed for PR 842"

トラブルシューティング

detached HEAD worktree

# 一時的に特定コミットを試す（branch 名なし）
git worktree add --detach ../portfolio-experiment abc1234def

# 作業を残すならブランチ化
cd ../portfolio-experiment
git switch -c experiment/results

detached worktree は 長期放置禁止。ブランチ名を付けて list で可視化する。

壊れた worktree 参照の強制修復

# admin ファイルだけ残った場合
git worktree list
# 手動でディレクトリ削除済みなら
git worktree prune -v
# それでも残る場合（上級）
rm -rf .git/worktrees/<id>
git worktree prune

セキュリティと secrets 管理

worktree ごとに .env.local を持つと、secrets のコピーが増える。

リスク	対策
古い API キーが review worktree に残る	remove 時に .env.local も削除する hook
本番 DATABASE_URL の誤使用	direnv または 1Password CLI で worktree パス別に inject
PR レビュー worktree への malware	レビュー専用 DB・staging キーのみ。本番 secrets 禁止

review worktree 用の .env.local テンプレート:

# .env.review.example — 本番値は絶対にコピーしない
DATABASE_URL=postgresql://localhost:5432/myapp_review
API_BASE_URL=https://staging-api.example.com
OPENAPI_VALIDATION_STRICT=true
LOG_LEVEL=debug

tmux / Zellij との組み合わせ

ターミナルマルチプレクサで window = worktree にすると、SSH 越しのリモート開発でも切り替えが速い。

#!/usr/bin/env bash
# tmux-worktrees.sh — 各 worktree に 1 window
SESSION="dev-portfolio"
REPO_ROOT="$(git rev-parse --show-toplevel)"

tmux has-session -t "${SESSION}" 2>/dev/null && tmux kill-session -t "${SESSION}"
tmux new-session -d -s "${SESSION}" -c "${REPO_ROOT}" -n "main"

git worktree list --porcelain | while read -r line; do
  if [[ "${line}" == worktree* ]]; then
    wt_path="${line#worktree }"
    if [[ "${wt_path}" != "${REPO_ROOT}" ]]; then
      win_name="$(basename "${wt_path}")"
      tmux new-window -t "${SESSION}" -n "${win_name}" -c "${wt_path}"
    fi
  fi
done

tmux attach-session -t "${SESSION}"

git worktree vs その他の手法

手法	向くケース	不向き
worktree	2+ ブランチの同時実行、長時間 dev サーバー	ディスク極小、ブランチ 1 個だけ
stash	15 分の中断、クリーンな diff	依存関係再起動が重い
clone 複数	完全隔離（別 origin 設定）	fetch 重複、ディスク 3 倍
コンテナ per branch	CI 再現、DB 完全分離	起動遅い、RAM 食う
WIP commit	個人開発の粗い保存	PR 汚染、review 不可

本番導入チェックリスト

よくある質問（FAQ 補足）

frontmatter の FAQ に加え、運用で出る細かい問いを補足する。

Q: git pull は各 worktree で必要ですか？
A: fetch はリモート共通だが、各 worktree の working tree は独立。main worktree で git pull しても feature worktree のファイルは変わらない。各ツリーで必要に応じて merge / rebase する。

Q: worktree 間で cherry-pick は普通ですか？
A: 非常に普通。hotfix worktree の 1 commit を feature worktree で git cherry-pick <sha> する。object DB 共有のため cherry-pick は軽い。

Q: LFS は worktree で動きますか？
A: Git LFS 2.3+ で worktree 対応。ただし各 worktree で git lfs install と pull が必要な場合がある。大容量バイナリ repo では clone 複数より worktree が有利なことが多い。

関連記事

この記事は 開発ツール・基礎 テーマの一環です。あわせて読むと理解が深まる関連記事をまとめました。

トピック	記事
Base64とは？仕組みから使い方まで解説	Base64とは？仕組みから使い方まで解説
Base64デコードで日本語が文字化けする原因と対処法	Base64デコードで日本語が文字化けする原因と対処法
JSON 整形ツールの使い方	JSON 整形ツールの使い方｜オンラインで安全に整形・圧縮
JSONの「Unexpected token」エラー原因と対処法	JSONの「Unexpected token」エラー原因と対処法
ハッシュ生成 - SHA-256/384/512をローカルで安全に計算	ハッシュ生成 - SHA-256/384/512をローカルで安全に計算
MD5 ハッシュ生成	MD5 ハッシュ生成｜md5 hashの使い方の使い方と注意点まとめ実務ガイド実践ガイド
正規表現でよく使うパターン10選	正規表現でよく使うパターン10選｜開発で役立つRegex
Markdown記法チートシート	Markdown記法チートシート｜コピペで使える一覧
Gitコマンドよく使う一覧	Gitコマンドよく使う一覧｜初心者向けクイックリファレンス
.envファイルのベストプラクティス	.envファイルのベストプラクティス｜機密情報を安全に管理する
URLエンコード（パーセントエンコーディング）の使い方	URLエンコード（パーセントエンコーディング）の使い方
HTMLエスケープ（サニタイズ）が必要な理由	HTMLエスケープ（サニタイズ）が必要な理由｜XSS攻撃を防ぐ基礎知識

まとめ

git worktree は 「ブランチ切り替えの税」 を払わずに並行開発するための公式機能だ。

• add / remove / prune の 3 点セットを習慣化し、同時 3〜5 worktree に抑える
• Cursor / VS Code では .code-workspace マルチルートが 2026 年のベストプラクティス
• OpenAPI CI や GitHub Actions 修正は専用 worktree で切り、CI バリデーション記事 の validate → lint → diff パイプラインをローカル再現してから push
• node_modules と PORT の重複にだけ注意——ディスク監視スクリプトで週次確認
• 終わった worktree は その日のうちに remove——「あとで」のまま残ると 3 ヶ月後に node_modules 墓地になる

git switch のたびに dev サーバーを止めていた時間を、実装とレビューと CI 修正に振り返れる。worktree は一度セットアップすれば チーム全員のスループット を上げる、低コストな開発インフラだ。