⚡
★ 86.6k

チャプター8：Git Worktreeとブランチ管理

モダンな機能開発には分離が必要です。現在の作業状態を不安定にせずに新機能を開発し、作業途中のものをstashせずにコンテキストを切り替え、常にブランチを切り替えることなく並行した作業ストリームを実行できなければなりません。Git worktreeはこれらすべてを解決します。

Git Worktreeとは？

git worktreeを使うと、同じリポジトリの複数のブランチをディスク上のそれぞれ独自のディレクトリに同時にチェックアウトできます。

worktreeがない場合、単一のリポジトリには一つの作業ディレクトリしかありません。ブランチを切り替えると、その一つのディレクトリ内のすべてのファイルが変更されます。コンテキストを切り替えるたびに、変更をstashするか、作業途中のものをcommitするか、または状態を失うリスクを冒す必要があります。

worktreeを使用すると、次のような状態にできます：

  • ~/projects/myapp/ は main ブランチ
  • ~/projects/myapp-feature-auth/ は feature/auth ブランチ
  • ~/projects/myapp-hotfix-123/ は hotfix/issue-123 ブランチ

3つはすべて同じリポジトリです。commit、tag、履歴は共有されています。しかし、各ディレクトリには独自の作業ツリーとステージングエリアがあり、他のものから完全に分離されています。

これが、v4.2.0で導入されたSuperpowersの必須worktree分離ポリシーの基盤です：すべての機能ブランチには独自のworktreeがあり、mainブランチは直接変更されません。

新しい開発ブランチの作成

新しい作業を開始する際は、以下の5つのステップに従ってください。

ステップ1：ディレクトリを選択する

worktreeディレクトリの名前をブランチ名に合わせます。メインの作業ディレクトリに隣接した場所に置きます：

# メインリポジトリの場所：
/Users/you/projects/myapp

# 新しいworktreeの場所：
/Users/you/projects/myapp--feature-user-auth

ダブルダッシュ規則（--）を使うと、プロジェクト名とブランチ名を視覚的に区別でき、lsでworktreeを簡単に識別できます。

ステップ2：ブランチとWorktreeを作成する

# メインリポジトリディレクトリ内から：
git worktree add ../myapp--feature-user-auth -b feature/user-auth

# これにより以下が作成されます：
# 1. feature/user-auth という名前の新しいブランチ
# 2. ../myapp--feature-user-auth に新しいディレクトリ
# 3. そのディレクトリが新しいブランチにチェックアウトされる

既存のブランチからworktreeを作成する場合：

git worktree add ../myapp--feature-user-auth feature/user-auth

ステップ3：安全性の確認

作業を始める前に、worktreeが正しくセットアップされていることを確認します：

cd ../myapp--feature-user-auth

# 正しいブランチにいることを確認
git branch --show-current
# 期待値：feature/user-auth

# worktreeがクリーンであることを確認
git status
# 期待値：nothing to commit, working tree clean

# 正しい場所からブランチを作成したことを確認
git log --oneline -5
# 最近のmainブランチの履歴がベースとして表示されるはず

このステップをスキップしないでください。間違ったブランチや汚れたツリーで作業を開始することは、混乱を招くバグの一般的な原因です。

ステップ4：プロジェクトのセットアップ

プロジェクトによっては、フレッシュなチェックアウト後に追加のセットアップが必要な場合があります。新しいworktreeで：

# 依存関係をインストールする（node_modulesが共有されていない場合）
npm install

# 必要に応じて環境ファイルをコピーする
cp ../myapp/.env.local .env.local

# 必要なファイルを生成する
npm run generate

正規のセットアップ手順については、プロジェクトのCLAUDE.mdまたはREADME.mdを確認してください。

ステップ5：ベースラインテスト

機能コードを一行も書く前に、完全なテストスイートを実行します：

npm test

作業を開始する前に、すべてのテストが通過しなければなりません。クリーンなチェックアウトでテストが失敗する場合、機能作業を開始する前に解決しなければならない既存の問題があります。このベースラインにより、作業中に発生したテストの失敗は、ベースブランチから引き継いだものではなく、自分の変更によるものだと確認できます。

開発ブランチの完了

機能が完成してすべてのテストが通過したら、作業に対して4つの選択肢があります。

4つの選択肢

選択肢使用するタイミング何が起きるか
Merge Locally小さな変更、書き込みアクセスがある、レビュー不要ブランチがmainにmergeされ、worktreeが削除される
Create PRチームプロジェクト、レビューが必要、またはCIゲートを通過する必要があるリモートにPRが作成され、PRがmergeされるまでworktreeが残る
Keep As-Is作業途中、mergeの準備ができていない、後で戻る可能性があるworktreeとブランチが保持され、何も行われない
Discard失敗した実験、不要になった作業ブランチとworktreeが永久に削除される

選択肢A：Merge Locally

# テストが通過していることを確認
npm test

# mainに切り替えてmerge
cd ../myapp
git checkout main
git pull origin main
git merge --no-ff feature/user-auth -m "feat: add user authentication"

# worktreeを削除
git worktree remove ../myapp--feature-user-auth

# ブランチを削除
git branch -d feature/user-auth

選択肢B：Pull Requestを作成する

# ブランチをリモートにプッシュ
cd ../myapp--feature-user-auth
git push -u origin feature/user-auth

# PRを作成（GitHub CLIを使用）
gh pr create --title "feat: add user authentication" --body "..."

# PRがレビューされてmergeされるまでworktreeは残る

選択肢C：Keep As-Is

何も操作は必要ありません。worktreeとブランチが残ります。忘れないように、コメントやissueに作業途中の状態を記録してください。

選択肢D：Discard

警告：これは永続的で、元に戻すことはできません。

discardオプションには明示的な確認が必要です。プロンプトが表示されたら**「discard」**という言葉を入力する必要があります。これにより、誤って作業を削除することを防ぎます。

# worktreeディレクトリを削除
git worktree remove --force ../myapp--feature-user-auth

# ローカルブランチを削除
git branch -D feature/user-auth

# リモートにプッシュしていた場合、リモートブランチも削除
git push origin --delete feature/user-auth

作業に価値がないと確信できる場合のみdiscardしてください。少しでも疑いがある場合は「Keep As-Is」を使用し、後で再検討してください。

複数のWorktreeの管理

リポジトリのすべてのアクティブなworktreeを確認するには：

git worktree list

出力の例：

/Users/you/projects/myapp              abc1234 [main]
/Users/you/projects/myapp--feature-auth  def5678 [feature/user-auth]
/Users/you/projects/myapp--hotfix-99   ghi9012 [hotfix/issue-99]

古いworktreeの参照をpruneするには（ディレクトリを手動で削除した後）：

git worktree prune

Mainブランチの保護

Superpowersプロトコルは、mainブランチについて一つの絶対的なルールを適用します：

mainに直接commitしてはなりません。すべての変更はブランチとworktreeを通じて行います。

これはv4.2.0の必須worktree分離ポリシーによって適用されます。小さな「クイック」な修正でも、worktreeを使用すべきです。常に分離した状態で作業するという規律により、問題のクラス全体を防ぐことができます：mainへの誤ったcommit、一つのブランチに混在した変更、そして変更をきれいにrevertできなくなること。

mainに直接commitしようとしていることに気づいたら、停止してください。worktreeを作成してください。30秒かかりますが、解決に何時間もかかる可能性のあるミスを防ぐことができます。