Git Worktree ワークフロー - 完全ガイド

このガイドでは、最適化されたデベロップメントワークフロー向けに gw CLI ツールを使用して Git worktree をマスターする方法を説明します。

目次

1. Git Worktree の基礎
2. gw を使用した Worktree の作成と管理
3. Worktree 間のナビゲーション
4. Worktree のリスト化と検査
5. 一般的なワークフローパターン
6. クリーンアップとメンテナンス
7. よくある問題のトラブルシューティング

---

1. Git Worktree の基礎

Git Worktree とは？

Git worktree を使用すると、単一のリポジトリに複数の作業ディレクトリを関連付けることができます。現在のディレクトリでブランチを切り替える代わりに、異なるブランチを別々のディレクトリで同時にチェックアウトできます。

従来のブランチ切り替え:

# 現在の作業が中断される
git checkout feature-a     # フィーチャー A で作業
git checkout feature-b     # コンテキストを切り替え、フォーカスを失う
git checkout main          # 緊急対応のため再度切り替え

Worktree の場合:

# 各ブランチが独自のディレクトリを持つ
/repo.git/main/           # Main ブランチはいつでも準備完了
/repo.git/feature-a/      # フィーチャー A の開発
/repo.git/feature-b/      # フィーチャー B を並列開発
/repo.git/hotfix-123/     # フィーチャーを中断せずに緊急対応

Worktree vs ブランチ切り替え vs クローン

アプローチ	メリット	デメリット
ブランチ切り替え	単一ディレクトリ、ディスク容量が少ない	作業が中断、スタッシュが必要、IDE が再インデックス
Worktree	並列作業、中断なし、Git 履歴を共有	作業ファイルのディスク容量がやや多い
クローン	完全な分離	大量のディスク容量、別の Git 履歴、同期が困難

Worktree が有効な場面

Worktree は以下に最適です:

• 並列フィーチャー開発 - コンテキスト切り替えなしで複数のフィーチャーで作業
• 緊急対応ワークフロー - フィーチャー作業を継続しながら緊急バグに対応
• コードレビュー - 現在の作業を中断せずに PR ブランチをチェックアウト
• テスト - 複数バージョンまたは設定を同時にテスト
• 長時間実行の実験 - メイン作業から実験ブランチを分離
• ビルドアーティファクト - 競合せずに別々のビルドプロセスを実行

Worktree の制限と注意点

Worktree が共有するもの:

• ✅ Git リポジトリ (.git ディレクトリ)
• ✅ コミット履歴とオブジェクト
• ✅ ブランチとタグ
• ✅ スタッシュ
• ✅ フック と設定

Worktree が共有しないもの:

• ❌ 作業ディレクトリファイル
• ❌ 未追跡ファイル
• ❌ node_modules (シンボリックリンク経由でない限り)
• ❌ ビルドアーティファクト
• ❌ .env ファイル (コピーされない限り)

重要な制限:

• 複数の worktree で同じブランチをチェックアウトすることはできません
• 各 worktree は独自の依存関係をインストールする必要があります (node_modules、vendor/ など)
• IDE ワークスペース設定を worktree ごとに調整する必要があります
• 一部の Git UI ツールは worktree サポートが限定されています

---

2. gw を使用した Worktree の作成と管理

はじめに: クローンと初期化

gw を使用して新しいリポジトリをセットアップする場合、1 つのステップでクローンと初期化ができます:

# リポジトリをクローンして gw を自動的にセットアップ
$ gw init git@github.com:user/repo.git

Cloning repository from git@github.com:user/repo.git...
✓ Repository cloned to repo

Setting up gw_root branch...
✓ Created gw_root branch

Initializing gw configuration...
✓ Configuration created

Creating main worktree...
✓ Created main worktree

✓ Repository initialized successfully!

自動的に以下を実行します:

1. --no-checkout でリポジトリをクローン
2. ベアリポジトリ用の gw_root ブランチを作成
3. デフォルトブランチを自動検出 (main、master など)
4. .gw/config.json に gw 設定を作成
5. デフォルトブランチ用の最初の worktree を作成
6. リポジトリディレクトリに .git サフィックスでネーミング (ベアリポジトリ規約)
7. リポジトリディレクトリに移動 (シェル統合)

設定付きクローン:

# auto-copy ファイルを設定してクローン
$ gw init git@github.com:user/repo.git \
          --auto-copy-files .env,secrets/ \
          --post-add "pnpm install"

# カスタムディレクトリにクローン
$ gw init git@github.com:user/repo.git my-project

# インタラクティブに設定してクローン
$ gw init https://github.com/user/repo.git --interactive

既存のリポジトリの場合:

既にクローンしたリポジトリがある場合、その中から gw を初期化します:

$ cd ~/projects/myapp
$ gw init

Auto-detected git root: /projects/myapp.git
✓ Configuration created successfully

gw add コマンド

gw add コマンドは、自動ファイルコピーとナビゲーション機能を備えた git worktree add の強化版です:

# 基本的な使用法 - 既存ブランチ用の worktree を作成
# 自動的に新しい worktree に移動
gw add feature-auth

# 自動ナビゲーションなしで worktree を作成
gw add feature-auth --no-cd

# 新しいブランチで worktree を作成
gw add feature-payments -b feature-payments

# デフォルトブランチではなく別のブランチから作成
gw add feature-payment-v2 --from develop

# 親フィーチャーブランチから子フィーチャーブランチを作成
gw add feature-auth-social --from feature-auth

# 特定のスタートポイントから作成
gw add hotfix-security -b hotfix-security main

# 強制的に作成 (他の場所で既にチェックアウトされていても)
gw add feature-test --force

リモート fetch 動作

新しいブランチを作成する場合、gw add は リモート優先アプローチ に従い、作業が最新のコードから開始されることを保証します:

内部で起こっていること:

$ gw add feat/new-feature

Branch feat/new-feature doesn't exist, creating from main...
Fetching latest from remote to ensure fresh start point...
✓ Fetched successfully from remote
Creating from origin/main (latest from remote)

Creating worktree: feat/new-feature

コマンドは以下を実行します:

1. feat/new-feature が存在しないことを検出
2. リモートから main の最新版をフェッチ (origin/main)
3. フレッシュなリモート ref からブランチを作成
4. origin/feat/new-feature へのプッシュを簡単にするため追跡を設定

この理由:

• 競合を防止: ブランチは古い local ブランチではなく、最新のリモートコードから開始されます
• 最新のコードを保証: チームの最新の変更に基づいて構築しています
• マージの苦労を減らす: 最終的にマージするときの驚きが少なくなります

オフライン/フォールバック動作:

リモート fetch に失敗した場合 (ネットワーク問題、オフライン作業、リモートが設定されていない場合)、動作はコンテキストに依存します:

# --from なし (デフォルトブランチ): 警告を出しますが local フォールバックを許可
$ gw add feat/offline

Branch feat/offline doesn't exist, creating from main...
Fetching latest from remote to ensure fresh start point...

⚠ WARNING Could not fetch from remote

Falling back to local branch. The start point may not be up-to-date with remote.
This is acceptable for offline development or when remote is unavailable.

Creating from main (local branch)

Creating worktree: feat/offline

# --from 付き: リモートから成功した fetch を要求、失敗時に終了
$ gw add feat/explicit --from develop

Branch feat/explicit doesn't exist, creating from develop...
Fetching latest from remote to ensure fresh start point...

ERROR Could not fetch from remote

Cannot create branch from develop because the remote fetch failed.
This would use a potentially outdated local branch.

Possible causes:
  • Network connectivity issues
  • Branch develop doesn't exist on remote
  • Authentication issues

Options:
  1. Check your network connection and try again
  2. Verify the branch exists: git ls-remote origin develop
  3. Use a different source branch: gw add feat/explicit --from <branch>
  4. Create without --from to use default branch: gw add feat/explicit

主な違い: --from は最新性が必須

• --from なし: デフォルトブランチを使用、local へのフォールバック (オフラインサポート)
• --from 付き: リモートからの成功した fetch が必須 (明示的なソースが最新であることを保証)

既存 Worktree へのナビゲーション

既に存在する worktree を追加しようとすると、gw add はそこへのナビゲーションを提案します:

$ gw add feature-auth

ℹ Worktree feature-auth already exists at:
  /projects/myapp.git/feature-auth

Navigate to it? [Y/n]:
# Enter キーを押してナビゲーション (デフォルト: Yes)、または 'n' でキャンセル

worktree をすでに作成したかどうか不確かな場合に便利です。シェル統合をインストール (gw install-shell) する必要があります。

自動ファイルコピー

gw add で worktree を作成する場合、.gw/config.json で設定されたファイルが自動的にコピーされます:

{
  "root": "/Users/you/projects/myapp.git",
  "defaultBranch": "main",
  "autoCopyFiles": [".env", ".env.local", "secrets/", "components/ui/.vercel/"]
}

コピーされるもの:

• 環境ファイル (.env、.env.local)
• シークレットと認証情報
• ローカル設定
• キャッシュディレクトリ (必要な場合)

auto-copy してはいけないもの:

• node_modules (新規にインストール、またはシンボリックリンク)
• ビルドアーティファクト (新規にビルド)
• 大容量バイナリファイル
• IDE 設定 (.vscode/、.idea/)

auto-copy を使用した worktree 作成の例:

$ gw add feature-new-dashboard

Creating worktree feature-new-dashboard...
✓ Branch 'feature-new-dashboard' set up to track 'origin/feature-new-dashboard'
✓ Worktree created: /projects/myapp.git/feature-new-dashboard

Copying files from main...
✓ Copied: .env
✓ Copied: .env.local
✓ Copied: secrets/api-keys.json
✓ Copied: components/ui/.vercel/

Done! Navigate with: gw cd feature-new-dashboard

注: ブランチは origin/main ではなく、独自のリモートブランチ (origin/feature-new-dashboard) を追跡するよう設定されています。これは -u origin <branch> を必要とせず、git push が正しいブランチにプッシュされることを意味します。

ネットワーク障害対応:

worktree を作成する場合、gw add は明示的にソースブランチを指定したかどうかにより異なる動作をします:

• --from <branch> 付き: リモートからの成功した fetch が必須です。fetch に失敗した場合 (ネットワーク問題、リモートにブランチが存在しない、認証問題)、コマンドは詳細なエラーメッセージと提案を表示して終了します。これにより、明示的にソースを指定する場合に最新のコードで作業していることを保証します。
• --from なし (デフォルトブランチ): fetch 失敗について警告を出しますが、local ブランチを使用した作成を許可します。これはオフライン作業やリモートが設定されていない場合のフォールバックを提供します。

後の手動ファイルコピーは gw sync

後でファイルをコピーする必要がある、または別のソースからコピーする場合:

# 設定されていれば、config から autoCopyFiles をすべてコピー
gw sync feature-auth

# main から現在の worktree に特定のファイルをコピー
gw sync feature-auth .env components/agents/.env

# 別の worktree からコピー
gw sync --from staging feature-auth .env

ブランチ追跡と detached HEAD 状態

ブランチ追跡 (推奨):

# origin/main からブランチを作成し、独自のリモートブランチを追跡
gw add feature-x

# ブランチ関係を表示
$ git status
On branch feature-x
Your branch is up to date with 'origin/feature-x'.

# リモート/ブランチを指定せずにプッシュ可能
git push  # origin/feature-x にプッシュ

注: gw add が新しいブランチを作成する場合、ブランチを作成したブランチではなく、origin/<branch-name> への上流追跡を自動的に設定します。これにより、git push が正しく機能することを保証します。

Detached HEAD (一時的な作業):

# 特定のコミットをチェックアウト
gw add temp-test --detach v1.2.3

# ブランチなし、単なるコミット
$ git status
HEAD detached at v1.2.3

プッシュするフィーチャーには追跡ブランチを使用します。古いコミットの一時テストまたは検査には detached HEAD を使用します。

ブランチ作成戦略

フィーチャーブランチ:

# main からブランチ
gw add feature-name -b feature-name main

# develop からブランチ
gw add feature-name -b feature-name develop

緊急対応ブランチ:

# 本番環境タグからブランチ
gw add hotfix-security -b hotfix-security v1.2.3

# 即座の修正のため main からブランチ
gw add hotfix-critical -b hotfix-critical main

リリースブランチ:

# develop からリリース候補を作成
gw add release-v2.0 -b release-v2.0 develop

---

3. Worktree 間のナビゲーション

gw cd を使用した高速ナビゲーション

gw cd コマンドは worktree へのスマートなナビゲーションを提供します:

# worktree のフルネーム
gw cd feature-authentication

# 部分一致 (最初の一致が選ばれます)
gw cd feat    # 最初の場合 feature-authentication とマッチ

# ブランチ名でスマートマッチング
gw cd auth    # 名前に 'auth' を含む worktree を検索

スマートブランチチェックアウト用の gw checkout (または gw co)

gw checkout コマンドは worktree を理解する git checkout のスマートなラッパーです:

# ブランチをチェックアウト - 他の worktree で既にチェックアウトされていればナビゲート
gw checkout main
# または別名を使用
gw co main

# ブランチが他の worktree でチェックアウトされている場合:
# Output: Branch main is checked out in another worktree:
#   /projects/myapp.git/main
# Navigating there...

# ブランチがリモートに存在するが local にない場合、worktree 作成を提案:
gw checkout feature-new
# Output: Branch feature-new exists on remote but not locally.
# Create a new worktree for it? [Y/n]:

gw checkout vs gw cd いつ使うか:

• ブランチを考えている場合は gw checkout <branch> を使用 (git checkout のように)
• ディレクトリ名を考えている場合は gw cd <worktree> を使用
• どちらも部分マッチングをサポートし、既存の worktree へのナビゲーション
• gw checkout はさらにリモートブランチを処理し、worktree 対応のエラーメッセージを提供

単に git checkout を使用しない理由:

worktree の場合、git checkout main は main が他の worktree でチェックアウトされている場合に失敗します:

$ git checkout main
fatal: 'main' is already checked out at '/projects/myapp.git/main'

gw checkout を使用すれば、エラーを表示する代わりにそこへナビゲートするだけです。従来の Git ワークフローから worktree ベースのワークフローへの移行時に摩擦を減らします。

シェル統合

npm 経由で gw をインストール後、シェル関数が自動的にインストールされます:

# これは実際にはバイナリではなく、シェル関数です
gw cd feature-auth

# シェル関数は以下を実行します:
# 1. 実際の gw バイナリを呼び出す
# 2. worktree パスを取得
# 3. 現在のシェルで ディレクトリを変更

シェル統合がインストールされているか確認:

# テスト
gw cd main
pwd  # main worktree へのパスを表示するはず

# インストールされていない場合、シェル統合を再インストール
gw install-shell

シェル統合機能:

• リアルタイムストリーミング出力 - gw add などのコマンドが生成されたときに出力がストリーミングされるようになりました (バッファリングなし)
• 自動ナビゲーション - gw add 完了後に自動的に新しい worktree へナビゲート
• スマートクリーンアップ - gw remove で現在の worktree を削除する場合、自動的にリポジトリルートへナビゲート

デベロップメント別名の場合:

gw-tools をローカルで開発している場合、デベロップメントコマンド用のシェル統合をインストールできます:

# デベロップメント用にインストール (実際のパスに置き換え)
gw install-shell --name gw-dev \
  --command "deno run --allow-all ~/path/to/gw-tools/packages/gw-tool/src/main.ts"

# 完全な統合で使用
gw-dev add feat-branch  # 出力がリアルタイムでストリーミング!
gw-dev cd feat-branch   # ナビゲーションが動作!

IDE ワークスペース管理

VS Code:

各 worktree を別々のウィンドウで開く:

gw cd feature-a
code .

または複数ルートワークスペースを使用:

// myapp.code-workspace
{
  "folders": [
    {
      "name": "Main",
      "path": "/projects/myapp.git/main"
    },
    {
      "name": "Feature A",
      "path": "/projects/myapp.git/feature-a"
    },
    {
      "name": "Feature B",
      "path": "/projects/myapp.git/feature-b"
    }
  ]
}

JetBrains IDE (WebStorm、IntelliJ など):

各 worktree が独自のプロジェクトになります:

gw cd feature-a
idea .

または複数のソースルートを単一のプロジェクトにアタッチします。

---

4. Worktree のリスト化と検査

gw list コマンド

リポジトリ内のすべての worktree をリスト化:

$ gw list

/projects/myapp.git/main          abc123f [main]
/projects/myapp.git/feature-auth  def456a [feature-auth]
/projects/myapp.git/hotfix-bug    ghi789b [hotfix-bug] (detached)
/projects/myapp.git/old-feature   jkl012c [feature-old] (locked)

Worktree 状態を理解する

通常の worktree:

/projects/myapp.git/feature-auth  def456a [feature-auth]

• パス、コミットハッシュ、ブランチ名

Detached HEAD:

/projects/myapp.git/temp  xyz789d (detached)

• ブランチなし、特定のコミットを指しています

ロック済み worktree:

/projects/myapp.git/protected  abc123f [protected] (locked)

• 最初にロック解除しない限り gw remove で削除できません

Prunable worktree:

/old/path/feature  abc123f [feature] (prunable)

• ディレクトリが移動または削除されましたが、参照がまだ存在

ブランチ名で Worktree を検索

# すべての worktree をリスト化
gw list

# grep でフィルタ
gw list | grep feature

# 特定のブランチを検索
gw list | grep "\[main\]"

メイン Worktree を識別

リストされた最初の worktree がメイン worktree (元のリポジトリ) です:

$ gw list
/projects/myapp.git/main  abc123f [main]  ← メイン worktree
/projects/myapp.git/feature  def456a [feature]

メイン worktree:

• 実際の .git ディレクトリを含んでいます
• 削除できません
• 他のすべての worktree の親です

---

5. 一般的なワークフローパターン

フィーチャーブランチ開発

シナリオ: 現在の作業を中断せずに新しいフィーチャーを開始

# 現在 main で作業中
pwd  # /projects/myapp.git/main

# フィーチャー worktree を作成
gw add feature-user-profiles -b feature-user-profiles

# 新しい worktree へナビゲート
gw cd feature-user-profiles

# フィーチャーで作業
npm install
npm run dev

# その間、main worktree は手付かずのまま

メリット: main ブランチはクリーンなままで、緊急対応または他の作業に対応可能です。

フィーチャーブランチを最新に保つ

シナリオ: フィーチャーブランチを main の最新変更で更新

# フィーチャー worktree で作業中
gw cd feature-user-profiles

# main の最新変更で更新 (設定された戦略を使用)
gw update

# または別のブランチから更新
gw update --from develop

# マージ戦略を強制 (config をオーバーライド)
gw update --merge

# リベース戦略を強制 (config をオーバーライド)
gw update --rebase

# 起こることをプレビュー
gw update --dry-run

git pull の代わりに gw update を使用する理由:

worktree で作業する場合、main が通常別の worktree でチェックアウトされているため、単に git pull で最新の main を pull することはできません。gw update コマンドはこれを解決します:

1. リモートから main (または指定されたブランチ) の最新版をフェッチ
2. マージまたはリベース戦略を使用して現在のブランチを更新
3. 競合に対応し、明確なガイダンスを提供

更新戦略:

• マージ (デフォルト): マージコミットを作成し、完全な履歴を保持
• リベース: コミットをリプレイして線形の履歴を作成、よりクリーンですが履歴を書き換える

デフォルト戦略を .gw/config.json で設定するか、--merge/--rebase フラグでコマンドごとにオーバーライド。

安全機能:

• コミットされていない変更がある場合はブロック (--force でオーバーライド可能)
• detached HEAD 状態の場合はブロック
• マージ/リベース競合が発生時に明確なガイダンスを提供

ネットワーク障害対応:

gw update コマンドは gw add と同様に、ネットワーク障害に対して異なる動作をします:

• --from <branch> 付き: リモートからの成功した fetch が必須です。fetch に失敗すると、詳細なエラーメッセージとトラブルシューティング手順を表示して終了します。これにより、明示的にソースを指定した場合に、潜在的に古い local ブランチから更新されることを防止します。
• --from なし (デフォルトブランチ): fetch 失敗について警告を出しますが、local ブランチを使用した更新を許可します。これはオフライン作業のフォールバックを提供します。

ワークフロー例:

# フィーチャーで作業を開始
gw cd feature-dashboard

# 数日間作業...
git add .
git commit -m "feat: add dashboard widgets"

# その間、main に新しい変更が追加
# フィーチャーブランチを最新 main で更新
gw update

# 競合がある場合、明確なガイダンスが表示されます:
# マージ競合の場合:
#   1. 競合ファイルを編集
#   2. git add <解決されたファイル>
#   3. git commit
# リベース競合の場合:
#   1. 競合ファイルを編集
#   2. git add <解決されたファイル>
#   3. git rebase --continue

# 作業を継続
git add .
git commit -m "feat: integrate new API endpoints from main"

メリット: worktree を切り替えたり、手動でフェッチ/マージを管理したりすることなく、フィーチャーブランチを最新に保つ。

フィーチャー作業を継続しながら緊急対応

シナリオ: フィーチャー作業中に本番環境のクリティカルバグが発生

# 現在 feature-dashboard で作業中
gw cd feature-dashboard
# コミットされていない変更の途中...

# 緊急対応 worktree を作成 (フィーチャー作業を中断しない)
gw add hotfix-login-bug -b hotfix-login-bug main

# 緊急対応へナビゲート
gw cd hotfix-login-bug

# バグを修正
vim src/auth/login.js
git add .
git commit -m "fix: resolve login timeout issue"
git push origin hotfix-login-bug

# フィーチャー作業に戻る
gw cd feature-dashboard
# すべてのコミットされていない変更がまだ存在!

メリット: stash、WIP コミット、またはコンテキスト喪失の必要がありません。

階層的フィーチャー開発

シナリオ: 親フィーチャーブランチに依存する関連フィーチャーを構築

場合によっては、まだマージされていない親フィーチャーブランチの上に構築する子フィーチャーブランチを作成する必要があります。--from オプションでこのワークフローを簡潔に実行できます:

# main から親フィーチャーを作成
gw add feature-auth

# 認証の基礎に取り組む
gw cd feature-auth
# ... 基本認証を実装 ...
git add .
git commit -m "feat: add basic authentication"

# auth ブランチから子フィーチャーを作成 (main ではなく)
gw add feature-auth-social --from feature-auth

# 子フィーチャーへナビゲート
gw cd feature-auth-social

# このブランチには feature-auth の認証基礎がすべて含まれます
# OAuth 統合を通じて social login を構築
# ... OAuth 統合を実装 ...
git add .
git commit -m "feat: add social login with OAuth"

メリット:

• 子フィーチャーはマージを待つことなく、親フィーチャーのすべてのコミットを自動的に含む
• 関連フィーチャーを並列開発でき、マージを待つ必要なし
• origin/feature-auth-social を追跡 (親ではなく) プッシュ用
• フィーチャー間の明確な依存関係
• --from により、ソースブランチの最新コードであることを保証するため、リモートからの fetch が必須

一般的なパターン:

# フィーチャーの実験的バージョン
gw add feature-dashboard-v2 --from feature-dashboard

# 異なる実装でのステージロールアウト
gw add feature-api-graphql --from feature-api
gw add feature-api-rest --from feature-api

# 環境固有のフィーチャーブランチ
gw add feature-payment-staging --from develop
gw add feature-payment-prod --from main

マージするタイミング:

1. 親フィーチャーを最初にマージ: feature-auth → main
2. 子フィーチャーを更新された main にリベース、またはマージ
3. 子フィーチャーをマージ: feature-auth-social → main

コードレビューワークフロー

シナリオ: チームメイトの PR をレビューしながら、自分の作業を中断しない

# レビュー用 worktree を作成
gw add review-pr-123 -b pr-123 origin/pr-123

# レビューへナビゲート
gw cd review-pr-123
npm install
npm test
npm run dev  # 変更をテスト

# コードレビューを実施、コメント追加
git checkout -b pr-123-suggestions
# 提案を追加...

# 自分の作業に戻る
gw cd feature-dashboard

# 完了したらクリーンアップ
gw remove review-pr-123

メリット: ワークスペースに影響を与えない、実際の環境でコードをレビュー。

複数バージョンを同時にテスト

シナリオ: フィーチャーを Node.js 18 と Node.js 20 でテスト

# 各テスト環境用に worktree を作成
gw add test-node18 -b feature-api
gw add test-node20 -b feature-api --force

# Node 18 環境をセットアップ
gw cd test-node18
nvm use 18
npm install
npm test

# Node 20 環境をセットアップ (別のターミナルで)
gw cd test-node20
nvm use 20
npm install
npm test

# 結果を比較

メリット: テストを並列実行、バージョン固有の問題を早期に検出。

長時間実行の実験ブランチ

シナリオ: コミットせずにリスク高いリファクタリングを試す

# 実験用 worktree を作成
gw add experiment-new-architecture -b experiment/new-arch

# 実験に取り組む (数日/数週間)
gw cd experiment-new-architecture
# ラディカルな変更...

# 他の worktree で main フィーチャー開発を継続
gw cd feature-payments
# 通常の作業を続行...

# 後で: 成功した場合はマージ、または失敗した場合は削除
gw cd experiment-new-architecture
git push origin experiment/new-arch  # チームで共有

# または破棄
gw remove experiment-new-architecture

メリット: コミットのリスクなしに自由に実験、main 開発に影響なし。

---

6. クリーンアップとメンテナンス

Worktree を削除

安全な削除:

# worktree を削除 (コミットは push またはマージ済み)
gw remove feature-completed

# 強制削除 (push されていないコミットがあっても)
gw remove feature-abandoned --force

保護されたブランチ (削除不可):

• デフォルトブランチ (通常は main、.gw/config.json で設定)
• gw_root ブランチ (ベアリポジトリルート)
• ベアリポジトリ worktree

起こること:

• 作業ディレクトリは削除される
• Git から worktree 参照が削除される
• ブランチはリポジトリに残る (別の場所でチェックアウト可能)

古い Worktree をクリーンアップ

安全な worktree を削除:

# 安全な worktree をすべてプレビュー (デフォルト動作)
gw clean --dry-run

# 年齢に関わらず安全な worktree をすべて削除
gw clean

# 設定されたしきい値より古い worktree だけを削除
gw clean --use-autoclean-threshold

# しきい値チェック付きで古い worktree をプレビュー
gw clean --use-autoclean-threshold --dry-run

# 強制削除 (安全チェックをスキップ - 危険!)
gw clean --force

動作方法:

• デフォルトモード: すべての安全な worktree を検索 (年齢チェックなし)
• --use-autoclean-threshold 付き: 設定されたしきい値より古い worktree だけを検索 (デフォルト: 7 日)
• デフォルトでは以下の worktree のみを削除:
  • コミットされていない変更なし
  • push されていないコミットなし
• 保護された worktree (決して削除されません):
  • ベアリポジトリ worktree
  • デフォルトブランチ (.gw/config.json で設定、通常は main)
  • gw_root ブランチ (ベアリポジトリルート)

クリーンアップ戦略:

コマンド	いつ使うか
gw clean	年齢に関わらず完了した作業をクリーンアップ
gw clean --use-autoclean-threshold	定期メンテナンス (古い worktree のみ)
gw prune --clean	積極的なクリーンアップとデフォルトブランチ保護

しきい値を設定:

# 初期化時に 14 日に設定
gw init --clean-threshold 14

# または `.gw/config.json` を手動で編集
{
  "cleanThreshold": 14
}

ワークフロー例 (デフォルトモード):

# クリーンアップされる安全な worktree をすべてチェック
$ gw clean --dry-run
INFO: Checking for safe worktrees to clean...

Worktrees to remove:
  ✗ completed-feature-1 (2 days old)
  ✗ completed-feature-2 (14 days old)

Skipped worktrees:
  ⚠ active-feature - has uncommitted changes

# レビューしてクリーンアップ
$ gw clean
Remove 2 worktree(s)?
Type 'yes' to confirm: yes

Removing completed-feature-1...
  ✓ Removed

Removing completed-feature-2...
  ✓ Removed

SUCCESS: Removed 2 worktree(s)

ワークフロー例 (しきい値モード):

# 7 日より古い worktree をクリーンアップする予定をチェック
$ gw clean --use-autoclean-threshold --dry-run
INFO: Checking for worktrees older than 7 days...

Worktrees to remove:
  ✗ old-feature-1 (14 days old)
  ✗ old-feature-2 (10 days old)

Skipped worktrees:
  ⚠ recent-feature - has uncommitted changes

# レビューしてクリーンアップ
$ gw clean --use-autoclean-threshold
Remove 2 worktree(s)?
Type 'yes' to confirm: yes

SUCCESS: Removed 2 worktree(s)

クリーンアップ戦略: gw clean vs gw prune --clean

gw ツールは異なるシナリオ向けに 2 つの相補的なクリーンアップコマンドを提供します:

年齢ベースのクリーンアップ: gw clean

• 設定されたしきい値より古い worktree を削除 (デフォルト: 7 日)
• 定期メンテナンスに良い
• 安全チェックを尊重 (コミットされていない変更、push されていないコミットなし)
• .gw/config.json 経由で設定可能

# 定期メンテナンス (週次)
gw clean --dry-run  # プレビュー
gw clean            # 古い worktree を削除

完全なクリーンアップ: gw prune --clean

• すべてのクリーン worktree を削除 (年齢に関わらず)
• 最初に git worktree prune を実行して管理データをクリーンアップ
• デフォルトブランチと現在の worktree を保護
• ディスク容量が重要な場合、またはアーカイブ前に良好

# 積極的なクリーンアップ (休暇前、アーカイブ前)
gw prune --clean --dry-run  # プレビュー
gw prune --clean            # すべてのクリーン worktree を削除

比較:

機能	gw clean	gw prune --clean
年齢ベース	はい (設定可能)	いいえ (すべてのクリーン削除)
安全チェック	はい	はい
デフォルトブランチを保護	いいえ	はい
git worktree prune を実行	いいえ	はい
ユースケース	定期メンテナンス	積極的なクリーンアップ

どちらをいつ使うか:

gw clean を使用:

• 週次/月次メンテナンスで古い worktree を削除
• 最近の worktree を保持しながら古いものをクリーンアップしたい場合
• 自動クリーンアップルーチンの一部

gw prune --clean を使用:

• プロジェクトをアーカイブまたは休止前
• ディスク容量を素早く解放したい場合
• ミニマルな worktree セットアップ (main ブランチ + 現在の作業) にリセット
• 主要なマイルストンまたはリリース完了後

ワークフロー例:

# 定期メンテナンス (週次)
gw clean --dry-run  # 古い worktree をプレビュー
gw clean            # 問題なければ削除

# 主要なクリーンアップ (四半期ごと、または休止前)
gw prune --clean --dry-run  # すべてのクリーン worktree をプレビュー
gw prune --clean            # すべてのクリーン worktree を削除

古い Worktree 参照をクリーンアップ

シナリオ: worktree ディレクトリを手動で削除

# 古い参照が表示される
$ gw list
/projects/myapp.git/main      abc123f [main]
/projects/myapp.git/deleted   def456a [feature] (prunable)

# 古い参照をクリーンアップ
gw prune

# 確認
$ gw list
/projects/myapp.git/main  abc123f [main]

Worktree のロック/ロック解除

誤った削除から worktree を保護:

# 本番環境デプロイ worktree をロック
gw lock production-deploy

# 削除しようとする (失敗)
$ gw remove production-deploy
fatal: 'production-deploy' is locked; use 'git worktree unlock' to remove

# 削除準備ができたらロック解除
gw unlock production-deploy
gw remove production-deploy

ディスク容量管理戦略

Worktree サイズを確認:

du -sh /projects/myapp.git/*
# 150M main
# 145M feature-auth
# 892M feature-payments  # node_modules が多い!

最適化戦略:

1. シンボリックリンクで node_modules を共有 (上級、注意深く使用):

# フィーチャー worktree で
rm -rf node_modules
ln -s ../main/node_modules node_modules

2. pnpm を使用 (worktree 間でパッケージを自動共有):

pnpm install  # worktree 間でパッケージを共有

3. 古い worktree を定期的に削除:

# リストしてアーカイブ
gw list | grep feature-old
gw remove feature-old-1 feature-old-2

4. 保持する代わりにアーカイブ:

# ブランチを push、worktree を削除
git push origin feature-complete
gw remove feature-complete
# 後で必要な場合は再作成可能

---

7. よくある問題のトラブルシューティング

"Worktree already exists" エラー

問題:

$ gw add feature-auth
fatal: 'feature-auth' already exists

解決:

# 既存の worktree をリスト化
gw list

# 古い worktree を最初に削除
gw remove feature-auth

# または別の名前を使用
gw add feature-auth-v2

Git Ref 競合 (ブランチ名階層)

問題:

$ gw add test
Cannot create branch test because it conflicts with existing branch test/foo

Git doesn't allow both refs/heads/test and refs/heads/test/foo

Git は階層型のネーミング競合を防止します (例: test と test/foo の両方) 。.git/refs/heads/ に同じパスがファイルでもディレクトリでもあるためです。

解決:

# オプション 1: 別の名前を使用
gw add test-new -b test-new

# オプション 2: 競合するブランチを削除
git branch -d test/foo
gw add test

# オプション 3: 競合する既存ブランチを使用
gw add test/foo

予防: 一貫したネーミング規約を使用。良い: feature/auth、feature/checkout。悪い: feature と feature/new を混在。

ロック済み Worktree 復旧

問題:

$ gw remove feature-x
fatal: 'feature-x' is locked

解決:

# worktree をロック解除
gw unlock feature-x

# これで削除可能
gw remove feature-x

破損した Worktree 状態

問題:

$ gw cd feature-x
fatal: 'feature-x' does not appear to be a git repository

解決:

# worktree 管理ファイルを修復
gw repair

# それでもダメな場合は削除して再作成
gw remove feature-x --force
gw add feature-x -b feature-x origin/feature-x

パーミッション問題

問題:

$ gw add feature-y
fatal: could not create work tree dir 'feature-y': Permission denied

解決:

# 親ディレクトリのパーミッションをチェック
ls -la /projects/myapp.git/

# パーミッションを修正
chmod 755 /projects/myapp.git/

# または sudo (非推奨)
sudo gw add feature-y

Git 管理ファイルの修復

問題:

$ git status
error: bad signature 0x00000000
fatal: index file corrupt

解決:

# 影響を受けた worktree で
rm .git/index
git reset

# または修復コマンドを使用
gw repair

# インデックスを再構築
git add .

ブランチ チェックアウト 競合

問題:

$ gw add feature-x
fatal: 'feature-x' is already checked out at '/projects/myapp.git/other-worktree'

解決:

# オプション 1: 既存の worktree を使用
gw cd feature-x  # /projects/myapp.git/other-worktree へ移動

# オプション 2: 新しいブランチを作成
gw add feature-x-new -b feature-x-new feature-x

# オプション 3: 強制的にチェックアウト (十分に理解した場合のみ)
gw add feature-x-copy -b feature-x-copy --force

シェル統合問題

問題: gw cd がナビゲートしない、またはパースエラー表示

# Zsh エラー例:
/Users/name/.gw/shell/integration-gw-dev.zsh:2: defining function based on alias `gw-dev'
/Users/name/.gw/shell/integration-gw-dev.zsh:2: parse error near `()'

解決:

# 通常の gw インストール用
gw install-shell

# デベロップメント別名の場合、既存の別名を最初に削除
# その後、--command フラグでインストール
gw install-shell --name gw-dev \
  --command "deno run --allow-all ~/path/to/gw-tools/packages/gw-tool/src/main.ts"

# シェルをリロード
source ~/.zshrc  # または ~/.bashrc

一般的な原因:

• 同じ名前の別名と関数の競合 (.zshrc から別名を削除)
• 古い統合スクリプト形式 (再インストールで修正)
• サポート対象外のシェル (zsh、bash、fish のみ)

エラー後のクリーンアップ

問題: 失敗した worktree 作成で部分的な状態が残る

解決:

# 部分的な worktree を削除
rm -rf /projects/myapp.git/failed-worktree

# Git 参照をクリーンアップ
gw prune

# クリーンな状態を確認
gw list

---

まとめ

これで以下を理解できました:

• ✅ Git worktree の基礎といつ使うか
• ✅ gw add で worktree を作成・管理
• ✅ gw cd で高速ナビゲーション
• ✅ フィーチャー、緊急対応、レビュー向けの一般的なワークフローパターン
• ✅ メンテナンスとクリーンアップ戦略
• ✅ よくある問題のトラブルシューティング

次のステップ

1. gw add で最初の worktree を作成
2. auto-copy 設定をセットアップ (config-management スキル を参照)
3. 自律的なワークフロー を探索 (autonomous-workflow スキル を参照)

その他のリソース

• Getting Started Example
• Parallel Development Example
• Troubleshooting Guide
• gw CLI Documentation

---

gw-tools スキルコレクションの一部