Git Worktree 徹底解説：1つのリポジトリ、複数の作業ディレクトリ

Git Worktree 解説動画の書き起こし版。8つのシーンで、「worktree って何？」から最初のコマンドまでをお届けします。

ある機能の途中で、突然本番環境が壊れたとします。多くの人がとる定番の手順はこうです。作業中の変更を stash して、main にチェックアウトし直し、バグを直して……そして自分の思考の文脈をもう一度組み立て直す。これでも動きますが、面倒です。切り替えるたびに時間と集中力を失い、たいていは IDE のきれいな状態も消えます。

Git worktree は、もっとスマートな答えをくれます。1つの作業ディレクトリを行ったり来たりさせるのではなく、1つのリポジトリから複数の作業ディレクトリを生やすのです。それぞれが自分のブランチにチェックアウトされ、同時に存在します。この記事は動画と同じ8つのシーンで構成しているので、自分のペースで読めます。

1つのリポジトリ、複数のフォルダ

1. Worktree って何？

worktree とは、単にディスク上の実際のディレクトリで、プロジェクトのチェックアウト済みコピーを保持し、特定のブランチに結びついているものです。普段は1つだけです。プロジェクトフォルダが1つ、1つのブランチ上に。worktree を使えば複数持てます。それぞれが本物のフォルダで、各々が自分のブランチ上にあり、すべてが同じリポジトリを指します。

それを表示するコマンドは小さいけれど強力です：

git worktree list

これは関連するフォルダをすべて出力します。worktree ごとに1行ずつ、パス、コミット、ブランチが表示されます。クローンもなければ .git の重複保存もなし。同じ家にドアをいくつか増やすだけのようなものです。

中央の .git ディレクトリから3つのフォルダが広がる様子を想像してください。main、feature/auth、hotfix/login です。どれも本物のディレクトリで、それぞれのファイルがチェックアウトされています。そして重要な点：各フォルダは自分自身の HEAD、つまり独立したブランチ状態を持っています。

1つのリポジトリ。独立した作業ツリー。

これが全体のメンタルモデルです。あとのすべては細部にすぎません。

共有リポジトリ、独立した作業ツリー

2. 内部でどう実現されているか

表面のシンプルさの裏には、いくつかの巧みなメカニズムがあります。4つの概念で全部説明できます。

メインとリンクされた worktree

もともとのプロジェクトフォルダがメインの worktree です。本物の .git ディレクトリ（内部では git-dir）を所有しています。あとで作るフォルダはすべてリンクされた worktree で、git-common-dir を通じてメインリポジトリを参照し、自分自身のコピーは持ちません。

独立した HEAD

あるフォルダ内でブランチをチェックアウトしても、他のフォルダはびくともしません。ファイルはそのままの場所に残ります。これは並列チェックアウトであり、並列クローンではありません。履歴は同じで、サンドボックスは別々です。

共有されるオブジェクトデータベース

すべての worktree は同じ .git/objects ストアを読み書きします。ある worktree で作ったコミットは、他のすべての worktree から即座に見えます。packfile の重複はなく、2回目のフルクローンよりずっと高速です。

唯一のルール：ロックファイル

Git は1つの制約を強制します——同じブランチを2つの worktree で同時にチェックアウトできないことです。やってみるとこうなります：

fatal: branch 'feature/auth' is already checked out

これはバグではなく機能です。2つの作業ツリーが同じブランチ名でこっそり分岐するのを防ぎます。解決策は簡単——別のブランチを使うか、別の worktree パスを使います。

worktree のコア概念

3. 従来のフロー vs Worktree フロー

多くの人は「stash して切り替える」というステップを先に覚えます。worktree のやり方と並べて見ましょう。

従来の Git フロー（苦労）：

  1. ある機能ブランチの真っ最中。
  2. 緊急のバグが舞い込む。
  3. 作業中の変更を git stash し、main にチェックアウトしてバグを直し、デプロイ。
  4. 戻ろうとする——そして今度は文脈の再構築。stash に何が入っていたか思い出し、競合しながら再適用し、IDE が忘れたファイルをまた開く。

切り替えるたびに集中力を消費します。それが摩擦です。

Worktree フロー（楽）：

  1. そのままの場所にとどまる。
  2. すでに main や hotfix/login にチェックアウトされた新しいフォルダをその場で作る。
  3. そこで直して、そこでデプロイ。
  4. もとの機能フォルダは無傷——stash もなければチェックアウトの往復もなし。

従来フロー vs worktree フロー

どちらも間違いではありませんが、並行タスクにおいては worktree が明確に有利です：1フォルダ・直列のコンテキスト 対 複数フォルダ・並列のコンテキスト。

4. ディレクトリ構造の中身

ファイルシステムを開いて、実際の姿を見てみましょう。

メインのプロジェクトフォルダ my-project/ があり、中にはおなじみの .git/ ディレクトリがあります。本当のリポジトリデータはここにあります。

機能ブランチ用のリンク worktree を作ります：

git worktree add ../my-project-feature-auth feature/auth

Git は兄弟フォルダ my-project-feature-auth を作ります。ここで微妙かつ重要な点：この新しいフォルダの中には完全な .git ディレクトリはありません。代わりにあるのは小さな .git ファイル——ポインタです。

gitdir: /path/to/my-project/.git/worktrees/feature-auth

この1行が全体の仕掛けです。本当のデータの在処を Git に教え、それぞれの worktree が自分の作業ファイルと HEAD 状態を持ちながら、同じコミット履歴とオブジェクトデータベースを共有できるようになります。

リンク worktree のディレクトリ構造

リンク worktree の src/ フォルダを開くと auth.ts があります。新機能のコードです。これを main と比べると違いは明白です。裏側は同じリポジトリ、ディスク上は完全に独立した作業ディレクトリ。これらのポインタを手で管理する必要はありません。Git がリンクをすべて面倒見てくれます。

5. よくあるユースケース

2つのブランチのコンテキストを同時に生かしておきたい瞬間こそ、worktree の出番です。

並行開発。 2つの機能、2つのブランチ、ゼロ干渉。自分が feature/auth と feature/billing を同時にやるにせよ、2人の開発者が同じリポジトリで作業するにせよ、フォルダは2つあればいい。stash の列もなければ「私の未コミット変更に触るな」という不安もありません。

コードレビュー。 自分のブランチの真っ最中に、同僚から PR のレビューを頼まれた。流れを断ち切って切り替える代わりに、相手のブランチで worktree を作ります。テストを走らせ、UI を触り、フィードバックを返す——あなたの元の作業はそのまま残ります。

ホットフィックス。 機能の途中で本番が壊れた。main やリリースブランチでホットフィックス worktree を作り、直して、テストして、デプロイして、マージ。終わったら機能作業に戻り、コンテキストロスはゼロ。

後で続ける。 進行中の作業がぐちゃぐちゃで、コミットするほどでもなく、stash するのも惜しい。その worktree をそのまま停めておき、次のタスク用に新しい worktree を開きます。数日後に戻ると、停めておいたフォルダはそのまま——IDE も git status もきれいな状態です。

worktree のよくあるユースケース

パターンはシンプルです。今の机を片付けるのではなく、新しい机をもう1つ開くのです。

6. AI Agent のワークフロー

AI agent が登場すると、このパターンはさらに重要になります。なぜならコンテキストこそが新しいボトルネックだからです。

問題——コンテキスト汚染。 複数の agent を1つのワークスペースに放り込むと、同じファイルと同じコンテキストウィンドウを奪い合います。Agent A が認証をリファクタリングし、Agent B が API ルートを書き換え、Agent C が UI を編集——すべて同時進行。共有コンテキストは雑音だらけになり、古い指示、間違ったファイルの前提、品質の低下を招きます。

解決策——worktree 隔離。 各 agent に自分の worktree を与えます。Agent A は認証モジュール用の専用ディレクトリを、Agent B は API パッケージでクリーンに、Agent C は UI に集中。各 agent はフレッシュな作業ディレクトリとクリーンなコンテキストを持ち、互いに干渉しません。

スケール——Monorepo 並行。 大きな monorepo ではこのパターンが美しく拡張します。専用 worktree で各 agent を特定のパッケージにスコープします。すべては1つのリポジトリ内にありますが、agent たちはクリーンで並列なストリームで動き、互いの足を踏みません。

AI agent ワークフローでの worktree

重要な洞察：worktree は各 agent に独立した作業ディレクトリとコンテキストを与えます——まるで1人1人に別々の机を与えるようなものです。良いプロンプトの代わりにはなりませんが、共有ワークスペースが引き起こす一連の問題を根本から取り除きます。

7. 自分で試す：インタラクティブ・プレイグラウンド

読むだけでなく触ってみたいなら、解説動画には実際のリポジトリに触らないサンドボックスがついています。

レイアウトはシンプルです。左が HEAD 位置付きのブランチグラフ、右がアクティブなディレクトリの worktree パネル、下がシミュレートされたターミナル、選択中の worktree のファイルツリーがあります。

# 持っている worktree をすべて見る
git worktree list

# 新しいものを追加（パネルとグラフに即座に表示される）
git worktree add ../my-project-hotfix hotfix/login

# 終わったら片付ける
git worktree remove ../my-project-hotfix

任意の worktree をクリックすればアクティブビューを切り替えてファイルを確認でき、 Deploy Agent ボタンで異なる agent を異なる worktree に割り当てられます。いつでも Reset でデモ状態に戻せます。

インタラクティブ worktree プレイグラウンド

実際のリポジトリで走らせる前に、筋肉記憶を育てる安全な練習場です。

8. コマンド早見表と次のステップ

worktree の道具一式はここにすべて——6つのコマンドでライフサイクル全体をカバーします：

コマンド 役割
git worktree add <path> <branch> 指定パスにリンク worktree を作成（ブランチ指定可）
git worktree list すべての worktree のパス・コミット・ブランチを表示
git worktree remove <path> worktree とその作業ファイルを安全に削除
git worktree prune 削除済み worktree の古いメタデータを掃除
git worktree lock <path> 誤削除を防止（長時間ジョブに便利）
git worktree unlock <path> 準備完了時にロック解除

今すぐコピーできる3つのコマンド：

git worktree add ../my-project-feature-auth feature/auth
git worktree list
git worktree remove ../my-project-feature-auth

Git worktree コマンド早見表

全体の流れはこれです：1つのリポジトリ → 複数のフォルダ → 並列の作業 → クリーンな agent コンテキスト。 これで、1つのリポジトリから複数の作業ディレクトリを作り、コンテキストをきれいに保ち、より効率的に働く方法を知りました。ひとりでも、AI agent と組んでも。

今週中に、最初の worktree を試してみてください。きっと「これなしで今までどうやってきたんだろう」と思うはずです。

Happy coding！

この記事は Git Worktree 解説動画の書き起こし版です。画像のプレースホルダ（images/*.jpg）は対応する動画フレームに置き換えられます。