こんにちは、StoreHero で CPO をしている永田です。
Claude Code を使っていると、複数のタスクを並列で走らせたくなる場面が増えてきます。そのときに便利なのが git worktree ですが、worktree をどこに展開するかは意外と情報が少ないです。
この記事では、私が気に入っている Bare Repository を使った構成を紹介します。
この記事で触れること / 触れないこと
触れること：
- git worktree のディレクトリ構成パターンの比較
- Bare Repository 構成のセットアップ手順
- この構成のメリットとデメリット
触れないこと：
- git worktree の基本的な使い方（
git worktree addなど） - Claude Code の並列実行の詳細な設定方法
- tmux との連携
なぜ worktree が必要なのか
Claude Code で複数のタスクを並列実行するとき、同じディレクトリで複数のエージェントを動かすとファイルの競合が起きます。ブランチ A の修正中にブランチ B の修正が混ざる、といった事故ですね。
git worktree を使えば、ブランチごとに独立したディレクトリを持てるので、この問題を回避できます。Anthropic の公式ドキュメントでも worktree の使用が推奨されています。
ただ、worktree をどこに展開するかは、公式ドキュメントでも深く触れられていません。実際に運用してみると、ここが意外と悩ましいポイントになります。
よく見るディレクトリ構成3パターン
調べてみると、大きく3つのパターンがあります。
| パターン | 構成例 | 特徴 |
|---|---|---|
| 隣接ディレクトリ |
~/projects/myapp/~/projects/myapp-feature-a/
|
シンプル。公式推奨 |
| .trees サブディレクトリ |
~/projects/myapp/~/projects/myapp/.trees/feature-a/
|
まとまりがいい |
| Bare Repository |
~/projects/myapp/.git/~/projects/myapp/main/~/projects/myapp/feature-a/
|
最もクリーン |
隣接ディレクトリは Anthropic 公式ドキュメントの例で使われている方法です。シンプルですが、プロジェクトが増えるとディレクトリが散らかりがちです。
.trees サブディレクトリは、メインリポジトリの中に worktree 用のディレクトリを作る方法です。まとまりはいいのですが、.gitignore への追加が必要です。
Bare Repository は、.git だけを持つリポジトリをルートに置き、すべてのブランチを worktree として展開する方法です。
Bare Repository 構成とは
私が採用している構成はこうです。
~/projects/myapp/
├── .git/ # bare repository
├── main/ # main ブランチの worktree
├── feature-a/ # feature-a ブランチの worktree
└── feature-b/ # feature-b ブランチの worktree
ポイントは、main ブランチも特別扱いせず、他のブランチと同じように worktree として展開することです。「本体」という概念がなく、すべてのブランチが対等に並びます。
なお、参考資料の Morgan Cugerone 氏のブログでは .bare ディレクトリ + .git ファイル（gitdir を指定）という方式が紹介されています。どちらも動作しますが、私は .git ディレクトリを直接使う方式の方がシンプルで好みです。
セットアップ手順
新規にリポジトリをセットアップする場合の手順です。
# 1. bare repository としてクローン
git clone --bare git@github.com:username/myapp.git myapp/.git
# 2. ディレクトリに移動
cd myapp
# 3. main ブランチを worktree として追加
git worktree add main main
# 4. 他のブランチも必要に応じて追加
git worktree add feature-a feature-a
これで、myapp/main/ や myapp/feature-a/ にそれぞれのブランチがチェックアウトされた状態になります。
fetch 設定の落とし穴
git clone --bare でクローンすると、デフォルトではリモートブランチの追跡設定が空になっています。
# ~/projects/myapp/ または worktree 内で実行
git config --get remote.origin.fetch
# 何も表示されない
この状態でも git push や git pull は動きます。ただし、チームメンバーが作った新しいブランチを取得できません。
git fetch origin
git branch -r
# 空のまま。origin/feature-x が表示されない
以下のコマンドで修正します。
git config remote.origin.fetch "+refs/heads/*:refs/remotes/origin/*"
git fetch origin
これでリモートブランチが正しく取得されるようになります。
既存リポジトリからの移行
既にクローン済みのリポジトリがある場合は、以下の手順で移行できます。
# 1. 既存リポジトリをリネーム
cd ~/projects
mv myapp myapp-old
# 2. bare repository として再クローン
git clone --bare myapp-old myapp/.git
# 3. fetch 設定を修正
cd myapp
git config remote.origin.fetch "+refs/heads/*:refs/remotes/origin/*"
# 4. main ブランチを worktree として追加
git worktree add main main
# 5. 問題なければ旧ディレクトリを削除
rm -rf ../myapp-old
リモートブランチから worktree を作成
チームメンバーが作成したブランチなど、リモートにしかないブランチを worktree として追加する場合は、以下のようにします。
# まず fetch してリモートブランチを取得
git fetch origin
# リモートブランチから worktree を作成
git worktree add feature-a origin/feature-a
# または、新しいブランチを作成する場合
git worktree add -b feature-new feature-new origin/main
worktree の削除
作業が完了した worktree は削除してディスク容量を節約できます。
# worktree を削除
git worktree remove feature-a
# 削除済み worktree の参照をクリーンアップ
git worktree prune
# 現在の worktree 一覧を確認
git worktree list
なぜこの構成が好きなのか
理由はいくつかあります。
まず、main を特別扱いしない設計が気に入っています。従来の構成だと、メインリポジトリ（main ブランチ）が「本体」で、worktree は「一時的な作業場所」という位置づけになりがちです。Bare Repository 構成では、すべてのブランチが同じレベルで並ぶので、この非対称性がなくなります。
次に、ディレクトリ構造がそのままブランチ構造を表すので見通しがいいです。ls するだけで、今どのブランチが展開されているかが一目でわかります。
ls ~/projects/myapp/
# .git/ main/ feature-a/ feature-b/
加えて、Claude Code との相性も良好です。複数のエージェントを並列で走らせるとき、myapp/agent-task-1/、myapp/agent-task-2/ のように展開先を増やせばいいだけです。命名規則も自由に決められますし、tmux のセッション名と対応させることもできます。
この構成のデメリット・注意点
万能ではないので、デメリットも挙げておきます。
まず、追加の設定が必要です。前述の fetch 設定は必須ですし、git clone --bare というコマンド自体が馴染みのない人も多いでしょう。チームで導入する場合は、セットアップ手順をドキュメント化しておく必要があります。
次に、一部の IDE が Bare Repository を正しく認識しないことがあります。VS Code でも bare repository と worktree の組み合わせで Source Control View が正常に動作しないケースが報告されています。Git Worktrees 拡張機能を使うと解消できる場合があります。
また、.env などの git 管理外のファイルは、worktree ごとに手動でコピーする必要があります。ただし、これは他の worktree 構成でも同じ問題なので、Bare Repository 固有のデメリットというわけではありません。
最後に、npm install や pip install などの依存関係のインストールも worktree ごとに必要です。これも他の構成と共通の話ですが、ディスク容量を消費する点は意識しておく必要があります。
まとめ
- git worktree のディレクトリ構成は、隣接ディレクトリ、.trees サブディレクトリ、Bare Repository の3パターンがある
- Bare Repository 構成は、すべてのブランチを対等に扱えて見通しがいい
- fetch 設定の変更が必要な点だけ注意
- Claude Code で複数エージェントを並列実行するときに相性がいい
Anthropic 公式が推奨している隣接ディレクトリ構成でも十分に機能しますが、もし「もう少しきれいに整理したい」と感じているなら、Bare Repository 構成を試してみてください。
Discussion