Git worktreeとは、1つのGitリポジトリに複数の作業ディレクトリを関連付け、異なるブランチを同時に開けるGitの機能です。
作業中のブランチを切り替えずに、機能開発や緊急修正、コードレビューなどの作業を並列で進められます。
通常、1つの作業ディレクトリで別のブランチを確認するには、変更をcommitしたり、git stashで一時的に退避したりしてからブランチを切り替える必要があります。
Git worktreeを使えば、現在の作業状態を残したまま別の作業ディレクトリを追加できるため、切り替えの手間や操作ミスを減らせます。
この記事では、Git worktreeの仕組みから、新規・既存ブランチでの作成方法、確認・削除、removeとpruneの違い、よくあるエラーまで解説します。
あわせて、Claude CodeなどのAIエージェントを使った並列開発の方法も、実際のコマンド例とともに紹介します。
Git worktreeとは
Git worktreeでは、最初に作成されたメインworktreeに加えて、必要に応じてlinked worktreeを追加できます。
まずは、複数の作業ディレクトリがどのように管理されるのか、基本的な仕組みを確認しましょう。
Git worktreeの仕組み
git initやgit cloneで最初に作成した作業ディレクトリは「メインworktree」と呼ばれます。git worktree addで追加する作業ディレクトリは「linked worktree」と呼ばれ、メインworktreeとは別の場所に作成されます。
メインworktreeとlinked worktreeは、コミット履歴やGitオブジェクト、ブランチの情報といったリポジトリの情報を共有します。
一方、HEADやindex（ステージ状態）、作業中のファイルは、worktreeごとに独立して管理されます。
そのため、linked worktreeのルートにある.gitは、通常のリポジトリにある.gitディレクトリとは異なります。
実体はディレクトリではなく、共通のGit管理領域を参照する1つのファイルです。
workspace/
├── my-project/ # メインworktree（main）
│ └── .git/ # 共通のGit管理領域（実体）
├── feature-login/ # linked worktree（feature/login）
│ └── .git # 共通領域を参照するファイル
└── hotfix-critical/ # linked worktree（hotfix/critical-bug）
└── .git # 共通領域を参照するファイル1つのworktreeでgit fetchを実行して取得したGitオブジェクトやリモート追跡情報は、共通領域に保存されるため、他のworktreeからも参照できます。
一方、依存ライブラリやビルド成果物、.envなどの環境設定は、worktreeごとに準備が必要な場合があります。この点については、後述の注意点で改めて説明します。
Git worktreeでできること
Git worktreeを使うと、次のような作業が可能になります。
複数ブランチを切り替えずに並行作業する
1つのworktreeで動作確認をしながら、別のworktreeで開発を続けられます。ブランチを切り替える回数そのものを減らせます。
開発中の状態を残したまま緊急修正を行う
作業中のファイルをコミットやgit stashで退避せずに残したまま、別のworktreeで緊急修正に対応できます。修正が終われば、元の作業へすぐ戻れます。
プルリクエストや別ブランチをレビューする
レビュー専用のworktreeを用意すれば、自分の作業環境を変更せずに他のブランチの内容を確認できます。動作を確認しながらコードを読み進められます。
AIエージェントごとに作業場所を分離する
Claude CodeなどのAIエージェントをworktreeごとに実行すれば、複数のエージェントが同じファイルを同時に書き換える事態を避けやすくなります。詳しい方法は後述します。
Gitとは？できることやGitに関する用語を解説
▶
ブランチ・git clone・git stashとworktreeの違い
Git worktreeは、通常のブランチ運用やgit cloneと似た場面で使われることがありますが、それぞれ役割が異なります。
まずは3つの方法を比較します。
| 項目 | 通常のブランチ運用 | git clone | git worktree |
|---|---|---|---|
| 役割 | 開発内容を分ける | リポジトリを複製する | 作業ディレクトリを増やす |
| 作成されるもの | ブランチ | 独立したリポジトリ | 共有リポジトリ配下の作業ディレクトリ |
| Git管理情報 | 1つの.gitを共有 | クローンごとに独立した.gitを持つ | Gitオブジェクトなどの共通管理情報を共有 |
| ブランチ切り替え | 都度切り替えが必要 | クローンごとに個別に切り替え可能 | worktreeごとに異なるブランチをチェックアウト可能 |
| ディスク使用量 | 少ない | クローンの数だけ増える | 作業ファイル分で済むことが多い |
| 向いている場面 | 通常の機能開発 | 完全に独立した環境が必要な場合 | 同じリポジトリで並行作業したい場合 |
1つのリポジトリには複数のブランチを作成できますが、通常の1つの作業ディレクトリ（worktree）で同時にチェックアウトできるブランチは1つだけです。
別のブランチを見るには、都度git checkoutでの切り替えが必要になります。
git cloneでリポジトリを複製すれば、クローンごとに異なるブランチをチェックアウトできます。
ただし、それぞれのクローンは独立した.gitディレクトリを持つため、コミット履歴やGitオブジェクトは共有されません。クローンを増やすほどディスク容量も消費します。
Git worktreeを使うと、1つの共有リポジトリのまま、異なるworktreeで複数のブランチを同時にチェックアウトできます。
Gitオブジェクトや履歴を共有するため、git cloneに比べてディスク使用量を抑えやすくなります。
git stashとの違いも整理しておきましょう。git stashは、変更内容を一時的に退避してからブランチを切り替える方法です。作業ディレクトリは1つのままで、退避と復元（stash pop）を都度行います。
一方、worktreeは、現在の作業状態を残したまま、別の作業ディレクトリを追加する方法です。
短時間の切り替えにはgit stashが手軽ですが、並行作業を続けたい場合や、作業環境ごと維持したい場合はworktreeが向いています。
Git worktreeの使い方
ここからは、実際にGit worktreeを操作してみましょう。
この記事では、次のディレクトリ構成を例として使用します。
workspace/
├── my-project/ # mainブランチ
├── feature-login/ # feature/loginブランチ
└── hotfix-critical/ # hotfix/critical-bugブランチリポジトリとworktreeの状態を確認する
まずは作業するリポジトリへ移動し、現在登録されているworktreeを確認します。
cd my-project
git worktree list出力例は次のようになります。
/Users/example/workspace/my-project a1b2c3d [main]ロック状態や削除可能かどうかなど、より詳しい情報を確認したい場合は--verboseを付けます。
git worktree list --verboseこの時点では、メインworktreeのみが表示されます。git worktree addで新しいブランチを作成するには基点となるコミットが必要なため、リポジトリの初回コミットがまだの場合は先に済ませておきましょう。
新しいブランチとworktreeを同時に作成する
新しいブランチの作成とworktreeの作成を同時に行う場合は、git worktree addに-bオプションを付けます。
git worktree add -b feature/login ../feature-login mainそれぞれの意味は次のとおりです。
-b feature/login… 新しく作成するブランチ名../feature-login… worktreeの作成先ディレクトリmain… 新しいブランチの作成元ブランチ
公式ドキュメントの構文では、オプションはパスより前に記載します。
作成元のブランチを省略した場合は、現在のHEADが基点になります。意図しないブランチを基点にしないよう、基点を明示したい場合はmainのようにブランチ名を書いておくと安全です。
既存のローカルブランチでworktreeを作成する
既に存在するブランチでworktreeを作成する場合は、-bオプションを付けずにブランチ名を指定します。
git worktree add ../develop develop指定したブランチが別のworktreeで既にチェックアウトされている場合は、エラーになります。
同じブランチは、複数のworktreeで同時に使用できません。詳しいエラー内容と対処方法は後述します。
リモートブランチをレビュー用worktreeで開く
他のメンバーが作成したリモートブランチを、読み取りや動作確認のために確認したい場合は、まず最新の情報を取得します。
git fetch origin
git worktree add --detach ../review-login origin/feature/login--detachを付けると、ブランチに関連付けずに特定のコミットをそのままチェックアウトできます。この状態は「detached HEAD（デタッチドヘッド）」と呼ばれ、その場でコミットしても、どのブランチにも属さない孤立したコミットになる点に注意が必要です。
動作確認だけが目的で、そのworktree上でコミットを作らない場合に向いています。
レビュー先で修正してコミットする場合は、リモートブランチを基点にローカルブランチを作成しておきましょう。
git worktree add -b review/feature-login ../review-login origin/feature/loginなお、リモート追跡ブランチであることを明示したい場合は、--trackを付けて次のように書くこともできます。
git worktree add --track -b review/feature-login ../review-login origin/feature/login-bでリモート追跡ブランチを直接指定した場合、多くの環境では自動的に追跡設定が行われますが、–trackを付けておくと、追跡関係が確実に設定されます。
作成後にgit pushやgit pullを行う際、追跡先を毎回指定する手間を省けます。
作成したworktreeで作業する
作成したworktreeは、通常のフォルダと同じように扱えます。feature-loginへ移動し、現在のブランチと状態を確認してみましょう。
cd ../feature-login
git branch --show-current
git statusgit branch --show-currentを実行すると、feature/loginが表示されます。
この状態になれば、あとは通常のブランチと同じように開発を進められます。
VS Codeで開く場合は、次のコマンドが使えます。
code .worktreeを削除する
作業が終わったら、不要になったworktreeを削除します。
git status
cd ../my-project
git worktree remove ../feature-login
git branch -d feature/loginこの操作について、次の点を覚えておきましょう。
git worktree removeで削除されるのは、linked worktree（作業ディレクトリ側）- ブランチは自動では削除されない
- ブランチも不要な場合は、worktreeを削除したあとに
git branch -dを実行する - 未コミットの変更や未追跡ファイルが残っているworktreeは、通常削除できない
削除できない場合は--forceで強制的に削除することもできますが、変更内容を失う可能性があるため、内容を確認せずに使うのは避けましょう。
removeとpruneの違い
git worktree removeとgit worktree pruneは、どちらもworktreeの削除に関わるコマンドですが、役割が異なります。
| 項目 | git worktree remove | git worktree prune |
|---|---|---|
| 用途 | 存在するlinked worktreeを安全に削除する | 手動削除などで残った古い管理情報を整理する |
| 対象 | 実際の作業ディレクトリとその管理情報 | 実体のないworktreeの管理情報のみ |
| 通常の削除での使用 | 基本的にこちらを使う | 通常は毎回実行しなくてよい |
フォルダをファイルマネージャーなどから直接削除してしまった場合、Gitはその変更を認識できず、git worktree listに存在しない情報が残ることがあります。
その場合はpruneを実行して整理します。
git worktree prune
git worktree list正常にremoveで削除できている場合は、pruneを毎回実行する必要はありません。
Git worktreeの主要コマンド・オプション一覧
ここまでに紹介したもの以外にも、Git worktreeにはいくつかのコマンドがあります。
使用頻度の高いものを中心に一覧で整理します。
| コマンド | 概要 |
|---|---|
| git worktree add | 新しいworktreeを作成する |
| git worktree list | 登録されているworktreeを一覧表示する |
| git worktree remove | 指定したworktreeを削除する |
| git worktree prune | 実体のないworktreeの管理情報を整理する |
| git worktree move | worktreeを別の場所へ移動する |
| git worktree lock | worktreeを保護し、pruneや削除の対象から外す |
| git worktree unlock | lockを解除する |
| git worktree repair | worktreeの管理情報を修復する |
moveは、外付けディスクやネットワーク越しに置いたworktreeなど、参照先の場所が変わった場合に使います。lock・unlockは、取り外し可能な媒体上のworktreeなど、常時マウントされない環境でpruneや削除を防ぎたい場合に使用します。repairは、worktreeやメインリポジトリのパスを移動したあとに、管理情報のつながりを修復したい場合に使用します。
いずれも通常の開発では頻繁に使うものではないため、必要になった際に公式ドキュメントを確認すれば十分です。
lockを使う際は、--reasonで理由を添えておくと、あとで見返したときに何のためのロックか分かりやすくなります。
git worktree lock --reason "USBドライブ上のため一時的に利用不可" ../portable-workあわせて、よく使うオプションも整理しておきます。
| オプション | 概要 |
|---|---|
| -b | 新しいブランチを作成しながらworktreeを追加する |
| –detach | ブランチに関連付けずにコミットをチェックアウトする |
| –force | 安全のための制限を無視して操作を実行する |
| –verbose | 実行結果やlist表示の詳細情報を表示する |
Git worktreeの活用シーン
開発中に緊急修正が入った場合
feature/loginブランチで作業している最中に、本番環境で不具合が見つかったとします。
この場合、origin/mainを基点にして、hotfix用のworktreeを作成します。
git fetch origin
git worktree add -b hotfix/critical-bug ../hotfix-critical origin/main作成元を省略すると、現在作業中のfeature/loginブランチを基点にhotfixブランチが作られてしまう可能性があります。
緊急修正では、origin/mainのように基点を明示しておくことが大切です。
なお、hotfix用のworktreeでは、依存関係の再インストールやビルドが必要になる場合があります。
筆者も緊急修正のためにworktreeを作ってすぐコードを直しにいったものの、依存関係のインストールを忘れていて、動作確認の段階で足止めを食った経験があります。急いでいる時ほど、まずnpm installなどのセットアップを済ませてから作業に入ることをおすすめします。
チームメンバーのコードを確認する場合
チームメンバーが作成したブランチを確認する方法は、前述のレビュー用worktreeでも紹介しました。
この活用シーンでのメリットは、自分が作業中のエディタや未コミットの変更を、そのまま残せる点です。
ブランチを切り替える方法では、確認前に自分の変更をコミットやgit stashで退避する必要があります。
worktreeであれば、その手間をかけずに、別のディレクトリでレビューを進められます。
複数のタスクや異なるバージョンを確認する場合
複数のタスクを同時に進めたい場合も、worktreeが役立ちます。
例えば、ログイン機能の開発と管理画面の改善を並行して進めたい場合、それぞれに専用のworktreeを用意すれば、ブランチの切り替えなしに作業できます。
過去のタグやコミットの内容を確認したい場合にも、同じ方法が使えます。
git worktree add --detach ../version-1 v1.0.0--detachを付けているため、v1.0.0タグが指すコミットの状態を、ブランチに影響を与えずに確認できます。
Claude CodeなどのAIエージェントでGit worktreeを使う方法
AIエージェントとworktreeの相性がよい理由
Claude CodeなどのAIエージェントを使った開発では、複数のセッションを同時に動かしたい場面があります。
worktreeを使うと、エージェントごとにファイルとブランチを分離できるため、同じファイルを複数のエージェントが同時に上書きするリスクを抑えられます。
機能開発、バグ修正、テスト作成などを、別々のセッションで並行して進めることもできます。
ただし、worktreeで作業場所を分けても、それぞれの変更を最終的にmainへマージする際には、内容によってコンフリクトが発生する可能性があります。worktreeは競合そのものをなくす機能ではなく、作業中の干渉を防ぐための機能です。
Claude Codeのworktree機能を使う
Claude Codeには、worktreeを使って独立したセッションを開始するオプションが用意されています。
claude --worktree feature-auth短縮形の-wオプションでも同じ操作ができます。
claude -w feature-authこのコマンドを実行すると、次のような場所にworktreeとセッションが作成されます。
- 作成先：
.claude/worktrees/feature-auth/ - 作成されるブランチ名：
worktree-feature-auth
Claude Codeで作成されるworktreeは、既定でリポジトリのデフォルトブランチ（origin/HEAD）を基点にします。
リモートが設定されていない場合やfetchに失敗した場合は、現在のローカルHEADが基点になります。
別のターミナルで名前を変えて同じコマンドを実行すれば、複数のセッションを並行して開始できます。
また、.claude/worktrees/以下はメインの作業ディレクトリから見ると未追跡ファイルとして表示されるため、.gitignoreに追加しておくとよいでしょう。
筆者も複数のClaude Codeセッションを同時に走らせる際にこの機能を使っていますが、それぞれが別のworktreeで動くため、ファイルの取り合いを気にせずセッション数を増やせる安心感は大きいと感じています。
.claude/worktrees/.envなどのgitignore対象ファイルを引き継ぐ
worktreeは新しく用意される作業ディレクトリのため、.gitignoreで除外されている.envなどのファイルは、そのままでは含まれません。
Claude Codeでは、プロジェクトのルートに.worktreeincludeというファイルを用意しておくと、これらのファイルを新しいworktreeへ自動でコピーできます。
.env
.env.local
config/secrets.local.json.worktreeincludeについて、次の点を押さえておきましょう。
- Claude Codeがworktreeを作成する際に使用するファイル
- コピー対象になるのは、gitignoreの対象になっているファイルのみ
- Gitで追跡されているファイルを重複コピーする機能ではない
node_modulesや.venv、ビルド成果物などは、必要に応じてworktreeごとに用意する
なお、git worktree addコマンドを直接使ってworktreeを作成する場合は、.worktreeincludeは自動的には適用されません。
この仕組みは、Claude Codeがworktreeを作成する場合に限られます。
作業終了後に変更を統合する
AIエージェントによる作業が終わったら、次の流れで内容を確認してから統合しましょう。
- AIエージェントが変更した内容を確認する
- テストを実行する
- worktree側でコミットする
- main側でマージ、またはプルリクエストを作成する
- 不要になったworktreeを削除する
AIエージェントが生成した内容は、確認しないままマージせず、変更内容とテスト結果を必ず確認してから統合してください。
ハーネスエンジニアリングとは？AIエージェントで生産性を最大化する手法を解説
▶
Git worktreeの注意点とよくあるエラー
Git worktreeを使う上でつまずきやすいポイントと、よくあるエラーへの対処法を整理しました。
まずは早見表で全体像をつかみ、詳しい内容は各項目で確認してください。
| 症状・エラー | 原因 | 対処 |
|---|---|---|
| worktreeが知らない間にprunable判定され、削除される | worktreeを.gitディレクトリの中に作成した | worktreeは.gitの外（隣のディレクトリなど）に作成する |
| 同じブランチを別worktreeで指定するとエラーになる | 同じブランチは複数のworktreeで同時にチェックアウトできない | 別のブランチを使うか、不要な方をremoveする |
| git worktree removeが失敗する | 未コミットの変更や未追跡ファイルが残っている | git statusで確認し、コミット・stash・破棄のいずれかを行う |
| .envやnode_modulesが見当たらない | Gitで追跡されていないファイルは新しいworktreeに含まれない | 個別に用意するか、Claude Codeなら.worktreeincludeを使う |
| メインworktreeを削除できない | メインworktreeはremoveの対象外 | 削除したい場合はリポジトリごと削除する |
| サブモジュールを含むリポジトリで不具合が出る | 複数worktreeでのサブモジュールサポートは不完全 | 事前に公式ドキュメントで制限事項を確認する |
worktreeの保存場所は.gitディレクトリの外にする
worktreeの作成先は、.gitディレクトリの外側に置くようにしましょう。
.gitディレクトリの中にworktreeを作成すると、Gitがその中身を不要な管理データと誤認し、git worktree pruneの対象（prunable）と判定して、意図せず削除してしまうことがあります。
この記事のサンプルのように、../feature-loginのような形で、メインworktreeと同じ階層の「隣」に作成するのが安全です。
プロジェクトフォルダの中に入れ子で作成した場合も、エディタの検索結果に複数ブランチのファイルが混在するなど混乱の原因になるため、避けた方が無難です。
同じブランチは複数のworktreeで使用できない
既にどこかのworktreeでチェックアウトされているブランチを、別のworktreeでも指定しようとすると、次のようなエラーが発生します。
fatal: 'feature/login' is already checked out at '/path/to/feature-login'この場合は、次の順番で対応します。
git worktree listで、そのブランチを使用しているworktreeを確認する- 使用していないなら、
git worktree removeで削除する - 同時に作業したい場合は、別のブランチを新しく作成する
--forceを使えばこの制限を回避できますが、意図せず同じブランチを複数の場所で操作してしまう原因にもなるため、通常の手順としてはおすすめしません。
未コミットの変更があると削除できない
worktree内に未コミットの変更や未追跡ファイルが残っている場合、git worktree removeは通常失敗します。
まずgit statusで状態を確認し、コミットする、git stashで退避する、不要な変更を破棄するのいずれかを行ってから、あらためて削除しましょう。
.envや依存ライブラリは自動で共有されない
Gitで追跡されていないファイルは、新しく作成したworktreeには含まれません。node_modulesや.venvなどは、通常worktreeごとに用意する必要があります。
また、複数のworktreeで開発サーバーを同時に起動する場合は、使用ポートなど、ローカルの設定が重複していないかにも注意しましょう。
メインworktreeはremoveで削除できない
最初にgit cloneまたはgit initを実行した場所は、メインworktreeとして扱われます。
メインworktreeはgit worktree removeの対象にはならず、削除できません。
サブモジュールを含むリポジトリには制限がある
サブモジュールとは、別のGitリポジトリを、自分のリポジトリの中にサブディレクトリとして組み込む仕組みのことです。
Git公式ドキュメントでは、サブモジュールを含むリポジトリを複数のworktreeでチェックアウトする際のサポートは、完全ではないと説明されています。
サブモジュールを使っているリポジトリでworktreeを利用する場合は、事前に公式ドキュメントで制限事項を確認しておきましょう。
Git worktreeに関するよくある質問
Git worktreeとgit cloneの違いは何ですか？
git cloneは、リポジトリ全体を複製し、Gitの管理情報も含めて独立したコピーを作成します。
一方、Git worktreeは、コミット履歴などのGit管理情報を共有したまま、作業ディレクトリだけを追加する機能です。
同じブランチで複数のworktreeを作れますか？
原則として作成できません。
既にどこかのworktreeでチェックアウトされているブランチを指定すると、エラーになります。同時に作業したい場合は、別のブランチを用意してください。
worktreeを削除するとブランチも削除されますか？
削除されません。
worktreeとブランチは別々に管理されているため、ブランチも不要な場合は、worktreeの削除後にgit branch -dで個別に削除する必要があります。
git worktree removeとpruneの違いは何ですか？
前述のとおり、removeは実在するworktreeを削除するコマンド、pruneは手動削除などで残った古い管理情報を整理するコマンドです。通常の削除にはremoveを使い、pruneは必要になったときだけ実行すれば十分です。
worktreeを作成すると.envやnode_modulesもコピーされますか？
通常はコピーされません。Gitで追跡されていないファイルは、新しいworktreeには含まれないためです。
Claude Codeを使っている場合は、.worktreeincludeファイルを用意しておくことで、.envなどgitignore対象のファイルを自動的に引き継げます。
まとめ
この記事では、Git worktreeの仕組みから使い方、注意点までを解説しました。
- Git worktreeは、複数の作業ディレクトリを1つのリポジトリへ関連付ける機能
- ブランチを切り替えずに、複数の作業を並行できる
- 作成元のブランチやコミットを明示すると、意図しないブランチ作成を防ぎやすい
- 通常の削除には
git worktree removeを使い、古い管理情報の整理にはpruneを使う - Claude CodeなどのAIエージェントを使った並列開発にも活用できる
- 作業後は、コミット、統合、worktreeの削除まで行う
まずは、自分のリポジトリで現在の状態を確認するところから始めてみましょう。
git worktree list参考資料
