CodexのWorktreeを別の作業机で理解する

Codexの設定画面にある「Worktree」。説明を読んでも、Gitやブランチの知識がないと、何のための機能なのか見当がつきにくいかもしれません。

先に核心だけを言えば、Worktreeは同じGitリポジトリを使いながら、作業中のファイルを置く場所を複数に分ける仕組みです。

「複数の担当が一つのプロジェクトをパーツ別に改造している。ただし、全員が同じGitを参照しているので、完成するまでは変更ファイルを物理的に混ぜない」

この理解は、かなり本質を捉えています。正確さのために直すべき点は、「全員が一つの名前付きブランチへ同時に入るわけではない」という部分だけです。多くの場合、同じコミットを出発点に、それぞれ独立したWorktreeで作業し、完成後にGitの操作で成果を統合します。

この記事では、Localを「あなたの机」、Worktreeを「Codexごとの別の机」、Gitを「全員で共有する履歴書庫」に置き換えて説明します。読み終えるころには、何が共有され、何が分離されるのか、成果をどう戻すのか、次のタスクをLocalとWorktreeのどちらで始めればよいのかを判断できるようになります。

>>>Amazonのお得な最新の情報はここ

サーバー管理者歴17年の筆者が選んだレンタルサーバー会社はここ

Worktreeは「同じGitを使う別の作業机」

Worktreeを理解するときは、Gitの内部構造から覚える必要はありません。まずは、一つのプロジェクトに対して、実際のファイルを広げる作業机を増やす仕組みだと考えてください。

現時点でCodex Worktreesは、ChatGPTデスクトップアプリ内のCodexで利用できます。あなたが普段使っているプロジェクトフォルダをLocal、そのプロジェクトにつながった別の作業フォルダをWorktreeとして扱い、Codexのタスクごとに作業場所を分けられます。

まず一言でいうと何なのか

普通のGitリポジトリでは、一つの作業フォルダにファイルを展開し、その場所で編集します。ブランチを切り替えると、同じ机の上に広げられている資料が、選んだブランチの内容へ入れ替わります。

Worktreeを追加すると、同じリポジトリにつながった作業フォルダをもう一つ作れます。さらに必要なら、三つ、四つと増やせます。それぞれのフォルダには、その場所で編集するためのファイル一式があります。

そのため、あなたがLocalで通常作業を続けている間に、Codexは別のWorktreeでログイン機能を変更できます。さらに別のCodexタスクを別のWorktreeで開き、決済機能やUIを変更することも可能です。Worktree側で編集中のチェックアウト済みファイルは、その時点ではLocal側の同名ファイルへ直接書き込まれません。

Local・Worktree・Gitを机と書庫に置き換える

関係を図にすると、次のようになります。

共有するGitリポジトリ
  ├─ コミット履歴
  ├─ Gitオブジェクトのデータベース
  └─ ブランチなどの参照情報
       │
       ├─ Local          あなたが普段使う机
       ├─ Worktree A     Codexがログイン機能を作る机
       ├─ Worktree B     Codexが決済機能を作る机
       └─ Worktree C     CodexがUIを変更する机

机の上にある作業ファイルは別々ですが、どの机も同じ履歴書庫につながっています。ここでいう「同じGitを共有する」とは、同じリポジトリの履歴やオブジェクトデータベースを利用するという意味です。複数のタスクが、一つの名前付きブランチを同時にcheckoutして共同編集するという意味ではありません。

Gitは原則として、同じ名前付きブランチを複数のWorktreeで同時にcheckoutさせません。Codexが複数の管理Worktreeを作れるのは、新しいWorktreeが通常は特定の名前付きブランチをcheckoutせず、そのブランチのHEADにあるコミットを起点として作業を始めるためです。

Google Driveの共同編集のように、誰かの入力がその場で全員へ見える仕組みではありません。同じ設計図を受け取った担当者が、それぞれの机で部品を作り、完成後にGitの操作で組立台へ持ち寄るイメージに近いでしょう。

「完成するまで物理的に混ぜない」はどこまで正しいか

「全部同じGitを参照しつつ、完成するまで物理的に混ぜない」という理解は、かなり本質を捉えています。正確に言い換えるなら、同じリポジトリ履歴を参照しながら、チェックアウトされたファイルと未コミット変更を作業場所ごとに分離する仕組みです。

例えば、Worktree Aで src/auth.ts を書き換えても、LocalやWorktree Bにcheckoutされている src/auth.ts がその編集によって直接書き換わることはありません。別のCodexタスクの書きかけコードが、Localのソースファイルへ途中から混ざるのを避けられます。

ただし、「作業フォルダが分かれているから、Local環境全体には絶対に影響しない」とまで考えるのは危険です。複数の作業場が同じデータベースを使う、同じポートでサーバーを起動する、同じ外部サービスへ接続する、checkoutの外にある共通ファイルを読み書きするといった場合は、互いに影響し得ます。Worktreeが直接分離するのは、各WorktreeにcheckoutされたファイルとGit上の作業状態です。

そして、完成した部品は放っておいても合体しません。成果を一つのブランチへ統合する役目は、mergeやPull RequestなどのGit操作が担います。CodexのHandoffは別の機能で、チャットとコードをLocalとWorktreeの間で安全に移し、同じ作業を別のcheckoutで続けるために使います。

つまりWorktreeは、「いつ、どの成果を統合するか」を決めやすくする分離の仕組みです。統合そのものを自動で済ませる機能ではありません。

共有されるものと分離されるもの

Worktreeの理解が曖昧になりやすいのは、「同じGitを使う」と「ファイルは別々」が同時に成り立つからです。共有される層と、作業場所ごとに分かれる層を切り分けると、仕組みがはっきり見えてきます。

リポジトリ履歴とオブジェクトデータベースは共有する

CodexのWorktrees公式ガイドでは、各Worktreeがリポジトリ内のファイルのコピーを持つ一方、コミットやブランチなどのGitメタデータを共有すると説明されています。

つまり、Worktreeは独立した別リポジトリではありません。Worktree Aでコミットを作れば、そのコミットは共有するリポジトリのオブジェクトデータベースへ保存されます。別のWorktreeからも、必要なGit操作を通じてそのコミットを参照できます。

ブランチ名やタグなどの参照情報も、同じリポジトリのものとして扱われます。ただし、これは「全Worktreeが同じブランチを同時に開く」という意味ではありません。Gitは通常、一つの名前付きブランチを一つのWorktreeでだけcheckoutできるように制限しています。

ここでいう共有とは、Gitが管理する履歴の土台が共通だという意味です。作業中の文字入力や未コミット変更がリアルタイム同期されるわけではありません。

checkoutされたファイルと未コミット変更はWorktreeごとに分かれる

エディタで直接開くソースコード、設定ファイル、画像などは、それぞれのWorktreeのフォルダに存在します。Worktree Aで保存した未コミット変更は、Worktree Bの同名ファイルへ自動では反映されません。

Local/src/auth.ts       C0の状態
Worktree-A/src/auth.ts  ログイン担当が変更中
Worktree-B/src/auth.ts  C0の状態
Worktree-C/src/auth.ts  C0の状態

この物理的な分離こそ、Codexで並行作業をするときの価値です。一つのフォルダを複数タスクが直接編集すると、片方がファイルを書き換えた直後に、もう片方が古い前提で上書きする危険があります。Worktreeを分ければ、少なくとも各checkout内の作業ファイルを途中で互いに踏み荒らす事故を避けられます。

一方で、作業フォルダの外にあるものは別問題です。共有データベース、同じポート、共通の外部API、ユーザー領域の共通設定ファイルなどは、Worktreeを分けても共有されたままの場合があります。ファイルのcheckoutが分離されることと、実行環境の全資源が隔離されることは同じではありません。

HEADとindexは作業場所ごとに持つ

少しだけGit用語に踏み込みます。

HEAD は、その作業場所が現在どのコミットやブランチを指しているかを示す目印です。index は、次のコミットへ入れる変更を準備する領域で、「ステージングエリア」とも呼ばれます。

Git公式のworktreeリファレンスによれば、追加されたWorktreeは現在のリポジトリへ接続され、リポジトリの共通情報を共有しつつ、HEAD や index などWorktree固有の情報を別に持ちます。

これによって、Localは main を見ながら、別のWorktreeは異なるコミットや別ブランチを見て作業できます。Worktree Aでファイルをステージングしても、そのステージング状態がWorktree Bのindexへ勝手に入ることはありません。

cloneやバックアップとの違い

プロジェクトフォルダを手作業で複製したり、git clone を複数回実行したりしても、見た目だけなら複数の作業場を作れます。しかし、それらはWorktreeとは管理方法が違います。

別々にcloneしたリポジトリは、それぞれが独立したGitオブジェクトデータベースと管理領域を持ちます。対してWorktreeは、一つのリポジトリへ接続された複数のcheckoutです。Git自身が「この作業場所は、このリポジトリに属するWorktreeである」と把握しています。

また、一般のGit Worktreeは、短命な作業場所に限定された機能ではありません。通常のGit操作で作ったWorktreeを、用途に応じて長期運用することもできます。Codex上の使い分けでは、タスク単位のCodex管理Worktreeが軽量で使い捨て寄りの作業場所にあたり、長期間維持する環境にはPermanent Worktreeが用意されています。Permanent Worktreeは自動削除されません。

ただし、Worktreeそのものはバックアップではありません。正式に残したい成果はブランチを作ってコミットし、必要ならリモートへpushします。さらに、Git履歴を共有していても、依存関係やビルド結果まで一つになるとは限りません。node_modules、Rustの target、Xcodeのビルド関連ファイルなどがWorktreeごとに生成されれば、その分だけディスク容量を使います。

ブランチとWorktreeは何が違うのか

「一つのブランチへ、みんなでよってたかって改造する」という表現には、Worktreeの目的がよく表れています。ただし、Git上ではブランチとWorktreeは別の役割を持ちます。この違いを押さえると、Codexの画面に出てくる detached HEAD や「Create branch here」がつながります。

ブランチは履歴の名前、Worktreeは物理的な作業場所

ブランチは、Gitの履歴がどの方向へ進んでいるかを示す名前付きの目印です。例えば main、feature/login、fix/payment-error といった名前があります。

Worktreeは、その履歴の内容を実際のファイルとして置き、編集する場所です。

ブランチ ＝ どの変更履歴を育てるかを示す名前
Worktree ＝ その履歴のファイルを広げる物理フォルダ

一つのWorktreeでブランチを切り替えられますし、一つのリポジトリに複数のWorktreeを接続できます。両者は関連しますが、同じものではありません。

Codexがdetached HEADで始める理由

Codexが管理する新しいWorktreeは、通常、名前付きブランチをチェックアウトせず、detached HEAD の状態で始まります。

言葉は難しそうですが、意味は単純です。「あるコミットの内容を開いているが、まだ特定の名前付きブランチの先端として作業していない」という状態です。

例えば main の現在地点であるC0からWorktreeを作った場合、そのWorktreeはC0のファイルを持って作業を始めます。しかし、最初から main そのものへぶら下がって変更を進めるわけではありません。

Codexがこの状態を使うことで、タスクを作るたびに不要なブランチ名を増やさず、複数のWorktreeを安全に作れます。成果を残す段階になったら「Create branch here」で、その地点から feature/login などの名前付きブランチを作れます。

同じ名前のブランチを二つのWorktreeで開けない

Gitは原則として、一つの名前付きブランチを同時に複数のWorktreeへチェックアウトさせません。Codex公式ガイドにも、ブランチを同時にチェックアウトできる場所は一つだけだと明記されています。

例えばWorktree Aが feature/login を開いている間、Localでも同じ feature/login を開こうとすると、Gitは「そのブランチは別のWorktreeで使用中」と止めます。

これは不便な故障ではなく、安全装置です。同じブランチの先端を二つの作業場所から別々に動かす混乱を防いでいます。

したがって、複数のCodexタスクは「一つの名前付きブランチへ全員で直接書き込む」のではありません。同じコミットを出発点にして、detached HEADまたは担当ごとの別ブランチで作業する、と捉えるのが正確です。

Codexで複数タスクを並行する具体例

ここからは、ログイン、決済、UIの三つを並行改造する場面で、実際に何が起きるかを追ってみましょう。重要なのは、作業中の分離と、完成後の統合を別の段階として考えることです。

mainのHEADからログイン・決済・UI担当を分ける

開始時点では、main のHEADがコミットC0を指しているとします。ChatGPTデスクトップアプリ内のCodexで新しいWorktreeを始めるときは、開始ブランチとして main を選びます。Codexは、そのブランチのHEADであるC0を起点に新しいWorktreeを作ります。

開始ブランチ main
        │
        └─ HEAD = C0
              ├─ Local      → あなたが通常作業
              ├─ Worktree A → ログイン機能を改造
              ├─ Worktree B → 決済機能を改造
              └─ Worktree C → UIを改造

一般のGitコマンドでは、git worktree add にcommit-ishを指定して特定のコミットなどを起点にできます。しかし、CodexデスクトップUIの操作説明では、任意コミットを選ぶのではなく、開始ブランチを選び、そのブランチのHEADから始まると理解してください。

また、開始ブランチにローカルの未コミット変更がある場合、Codexはその変更を新しいWorktreeへ適用します。したがって、常に「コミットC0の完全に無変更な状態から始まる」とは限りません。Local側の作業内容を含めて開始したくない場合は、Worktreeを作る前に開始ブランチの状態を確認する必要があります。

片方の未完成変更がほかのcheckoutへ直接入らない状態

開始後は、ログイン担当が認証処理とログイン画面を変更し、決済担当が支払い処理を変更し、UI担当がテーマやレイアウトを変更します。各Worktreeにcheckoutされたファイルは別々なので、Worktree Aでログイン画面が半分まで完成していても、その編集がWorktree BやLocalの同名ファイルへ直接書き込まれることはありません。

これは遅延でも同期不良でもなく、Worktreeの意図した動作です。あるタスクの途中変更によって、別のタスクのソースファイルがその場で書き換わるのを防げます。

ただし、各タスクの実行環境まで完全に隔離されるわけではありません。例えばWorktree AとLocalが同じ開発用データベースへ書き込めば、データの変化は双方から見える可能性があります。同じポートでサーバーを起動すれば衝突し、同じ外部サービスやcheckout外の共通ファイルを使えば、相互に影響することもあります。

Worktreeが保証する中心は、checkoutされたファイルとGitの作業状態を分けることです。アプリ実行時の共有資源については、ポート番号、データベース、環境変数、外部サービスの接続先を別途管理する必要があります。

また、担当同士に依存関係がある場合も調整が必要です。決済機能がログイン担当の新しい認証APIを前提にするなら、Worktree BはWorktree Aの未コミット変更を自動では利用できません。先に共通インターフェースを決める、ログイン側のコミットを取り込む、統合順序を決めるといった通常の開発設計は、Worktreeを使っても残ります。

完成後はmergeやPull Requestで成果を統合する

三つの担当が完成したら、成果を名前付きブランチやコミットとして残し、Gitの操作で統合します。

ログイン用ブランチ ─┐
決済用ブランチ   ──┼─ merge／Pull Request → 完成版
UI用ブランチ     ──┘

各成果を順番にmergeする方法もあれば、リモートへpushしてPull Requestを作る方法もあります。必要なコミットだけを選んで取り込む cherry-pick もGitの選択肢です。

ここでHandoffの役割を混同しないことが大切です。Handoffは、複数ブランチの成果を一般的に統合・マージする機能ではありません。CodexのチャットとコードをLocalとWorktreeの間で安全に移し、同じ作業を別のcheckoutで続けるための機能です。

したがって、ログイン、決済、UIの三成果を一つへ組み立てるなら、中心になるのはmergeやPull Requestです。Worktreeで進めていた一つの作業を普段のLocal環境へ持ち帰りたいなら、Handoffを使います。

なお、ファイルが別なら必ず無条件で統合できるとは限りません。同じ行を異なる内容へ変更すればマージ競合が起きます。別ファイルでも、ログイン担当が認証データの形式を変え、決済担当が古い形式を前提にしていれば、設計上の食い違いが起きます。Worktreeは作業途中の踏み荒らしを防ぎますが、部品同士の整合性まで自動で設計してくれるわけではありません。

Codex Worktreeを始めて成果を戻すまで

Codex上の流れは、「開始ブランチを選ぶ」「独立したWorktreeで作業する」「作業をどこで続け、成果をどう統合するかを選ぶ」の三段階です。HandoffとGitの統合操作を分けて考えると、迷いにくくなります。

ChatGPTデスクトップアプリで開始ブランチを選ぶ

Codex Worktreesは現時点で、ChatGPTデスクトップアプリ内のCodexから利用できます。Gitリポジトリを対象に新しいタスクを始める際、Worktreeを選択し、開始ブランチとして main などを指定します。

Codexは、選択した開始ブランチのHEADを起点に、新しい管理Worktreeを作ります。デスクトップUIの説明としては「任意のコミットを選ぶ」のではなく、「開始ブランチを選ぶと、そのHEADから始まる」と捉えるのが正確です。

開始ブランチにLocalの未コミット変更がある場合、Codexはその変更を新しいWorktreeへ適用します。まだコミットしていない変更も引き継いで作業を続けられる一方、純粋なブランチHEADだけを起点にしたつもりでいると、Worktreeの初期状態を見誤ります。新しいタスクへ持ち込みたくない変更があるなら、開始前にLocalの状態を確認してください。

Worktree rootはCodex管理Worktreeの保存先

設定画面にある「Worktree root」は、Codexが管理するWorktreeを保存する親フォルダを決める項目です。元のプロジェクト自体を移動する設定ではありません。

CodexのWorktrees公式ガイドによれば、既定では $CODEX_HOME/worktrees の下にCodex管理Worktreeが作られます。一般的な配置イメージは次のとおりです。

/Users/you/Desktop/my-app/              元のプロジェクト、Local
$CODEX_HOME/worktrees/.../my-app/       Codex管理Worktree

Codex管理Worktreeは、タスク単位で使う軽量で使い捨て寄りの作業場所です。一般のGit Worktreeそのものは長期運用もできますが、Codexで同じ別作業場を長く維持したい場合はPermanent Worktreeを使います。Permanent Worktreeは自動削除されません。

.worktreeincludeでGit管理外の準備ファイルをそろえる

新しいWorktreeには、Gitで管理されているファイルがcheckoutされます。しかし、.env、.env.local、ローカル設定など、.gitignore の対象になっているファイルは通常そのままではそろいません。

Codex管理Worktreeを作るときに必要な無視ファイルをコピーしたい場合は、リポジトリのルートに .worktreeinclude を置き、対象パスや .gitignore 形式のパターンを記述できます。

# .worktreeinclude
.env
.env.local
config/local-settings.json

.worktreeinclude は、Gitに追跡されていない対象ファイルを新しいCodex管理Worktreeへコピーするための仕組みです。また、Handoffではgitignore対象ファイルは通常移りません。Worktree側でアプリを動かすために必要なら、Handoff任せにせず、.worktreeinclude で管理Worktreeの作成時からそろえる設計にします。

秘密情報を含むファイルを指定すれば、その実ファイルのコピーがWorktreeにも作られます。Gitへコミットされるわけではありませんが、保存先とアクセス権限の管理には注意が必要です。

Worktree側でCreate branch hereして統合へ進む

Codex管理Worktreeは通常detached HEADで始まります。その成果を名前付きの開発系列として残したい場合は「Create branch here」で、現在地点から担当ブランチを作ります。

ログイン機能なら feature/login、UI変更なら feature/dark-theme といった名前を付けられます。その後は一般的なGit作業と同じです。

1. Worktreeでタスクを完成させる
2. 「Create branch here」で担当ブランチを作る
3. 変更をコミットする
4. 必要ならリモートリポジトリへpushする
5. mergeまたはPull Requestで統合する

複数のWorktreeで作った成果を一つにまとめるのは、このmergeやPull Requestの役割です。Handoffは、複数成果を自動的に合体させる代替操作ではありません。

HandoffでチャットとコードをLocalへ移す

Handoffは、CodexのチャットとコードをLocalとWorktreeの間で安全に移し、同じ作業を別のcheckoutで続けるための機能です。

例えば、CodexがWorktreeで実装を進めたあと、普段使っているIDEやLocalの開発環境で続きを確認したい場合があります。そのとき「Hand off → Local」を選べば、チャットの文脈とコードをLocal側へ移し、同じ作業を継続できます。必要に応じて、Localから元のWorktreeへ戻すこともできます。

ここでも役割分担は明確です。

成果を一つの履歴へ統合する    → merge／Pull Request
作業場所をLocalへ移して続ける → Handoff

Handoffでは、.env などgitignore対象ファイルは通常移りません。Localでは動くのにWorktreeへ移したら設定が足りない、という場合は、.worktreeinclude の対象やWorktree側の環境設定を確認します。

Worktree側を担当ブランチとして仕上げるなら、Handoffせず、そのWorktreeでコミット、push、Pull Requestまで進められます。普段の作業場へ持ち帰って続きを行いたいならHandoffを使います。どちらが正解というより、「成果を統合したいのか」「作業場所を移したいのか」で選ぶ機能が違うのです。

Worktreeが解決しない問題と使い分け

Worktreeは、同じGitリポジトリを使う作業場所を分け、並行作業中のファイルが直接混ざるのを防ぐ仕組みです。ただし、あらゆる開発環境を完全に隔離し、完成した成果まで自動で統合してくれるわけではありません。

分離される中心は、各Worktreeにcheckoutされたファイルと、HEADやindexなどのGit作業状態です。複数の作業場が同じデータベース、ポート、外部サービス、checkout外の共通ファイルを使えば、そこでは互いに影響する可能性があります。この境界を知っておくと、「ファイルは別なのに動作がぶつかる」「最後に自動で合体すると思っていた」といった行き違いを避けられます。

同じ行を触ればマージ競合は起こる

Worktree AとWorktree Bが別々のファイルを変更していれば、成果は比較的統合しやすくなります。

Worktree A: src/auth.tsを変更
Worktree B: src/payment.tsを変更
Worktree C: src/theme.cssを変更

しかし、二つの担当が package.json の同じ行を異なる内容へ変更した場合、merge時に競合する可能性があります。Gitには「どちらの変更を正解として残すべきか」という設計判断まではできません。

違うファイルを変更していても安心とは限りません。ログイン担当が認証データの形式を変更し、決済担当が古い形式を前提に実装していれば、行単位の競合がなくても統合後に動かないことがあります。

Worktreeが防ぐのは、主に作業途中のファイルを別タスクが直接上書きすることです。マージ競合や部品同士の設計矛盾は残ります。担当範囲を分ける、共通インターフェースを先に決める、依存関係の強い変更は順番に進めるといった責任分担は、Worktreeを使っても必要です。

実行時の資源も同様です。Worktree AとLocalが同じ開発用データベースへ書き込めば、データの変化は双方から見える可能性があります。同じポートでサーバーを起動すれば衝突し、同じ外部APIやユーザー領域の共通設定を使えば、片方の操作がもう片方へ影響することもあります。必要に応じて、ポート番号、データベース、環境変数、外部サービスの接続先をWorktreeごとに分けてください。

.envなど無視ファイルは自動で揃わない

Gitで管理されているファイルは新しいWorktreeにもcheckoutされます。一方、.env、.env.local、ローカル専用設定など、.gitignore の対象ファイルは通常そのままではそろいません。

そのため、新しいWorktreeでアプリを起動したら、環境変数やローカル設定が足りず動かなかった、ということがあります。これはソースコードの不具合とは限りません。別の作業机に、Git管理外の備品が置かれていない状態です。

Codex管理Worktreeを作るときに必要な無視ファイルをコピーしたい場合は、リポジトリのルートに .worktreeinclude を置き、対象パスや .gitignore 形式のパターンを記述できます。

# .worktreeinclude
.env
.env.local
config/local-settings.json

この仕組みはCodexのWorktrees公式ガイドで案内されています。Handoffではgitignore対象ファイルは通常移らないため、Worktree側で必要になるファイルは、Handoff任せにせず .worktreeinclude で新しい管理Worktreeへコピーできるようにしておくと分かりやすくなります。

ただし、秘密情報を含むファイルを指定すると、その実ファイルのコピーがWorktreeにも作られます。Gitへコミットされるわけではありませんが、保存先とアクセス権限には注意が必要です。

保持数・自動削除・ディスク容量を管理する

Codex管理Worktreeは、タスク単位で使う軽量で使い捨て寄りの作業場所です。Codex公式ガイドに記載された現行の既定では、最近の15個が保持され、設定から上限を変更したり、自動削除を無効にしたりできます。

ピン留めされたタスクや実行中のタスクは通常の整理対象とは扱いが異なり、Permanent Worktreeは自動削除されません。古いCodex管理Worktreeが整理される場合、Codexは削除前に作業内容のスナップショットを保存し、後からタスクを開いたときに復元できるようにします。

ただし、この復元機能を正式なバックアップの代わりにするべきではありません。残したい成果は、ブランチとコミットとしてGit履歴へ保存し、必要ならリモートリポジトリへpushするのが基本です。

ディスク容量にも注意が必要です。WorktreeはGitオブジェクトデータベースを共有しますが、checkoutされた作業ファイルや、Worktree内で生成される依存関係、ビルド結果まですべて共有するわけではありません。node_modules、Rustの target、Xcodeのビルド関連ファイルなどがWorktreeごとに作られれば、その数に応じてストレージ消費が増えます。

最初は自動削除を有効にしたまま既定値を使い、容量が気になったら保持数を減らす考え方で十分です。長く残す必要がないタスク用Worktreeを、念のためという理由だけで大量に保持する必要はありません。

Local・管理Worktree・Permanent Worktreeの選び方

次のタスクをどこで始めるかは、作業を隔離したいか、並行作業が必要か、同じ作業場所をどれだけ長く維持したいかで判断できます。

Codexタスクが一つだけで、変更が普段のIDEへすぐ現れてよいならLocalで十分です。自分が編集中のcheckout済みファイルへCodexの途中変更を直接入れたくない場合や、複数の機能を並行して進めたい場合はCodex管理Worktreeが役立ちます。

一般のGit Worktreeそのものは、短命な用途に限定されていません。Git公式のworktreeリファレンスに沿って作成したWorktreeを、必要に応じて長期運用することもできます。

Codex上では、通常の管理Worktreeをタスク単位の一時的な作業場として使い、リリースブランチの保守や次期版開発のように同じ環境を維持したい場合はPermanent Worktreeを選ぶ、と考えると整理しやすくなります。最初から複雑に使い分ける必要はありません。まずは管理Worktreeで「別机」の感覚をつかみ、長期運用が必要になったときだけPermanent Worktreeへ進めばよいでしょう。

Gitリポジトリでなければ利用できない

WorktreeはGitの機能です。そのため、対象のプロジェクトがGitリポジトリでなければ利用できません。Codexの設定画面にWorktree項目が表示されていても、現在開いているフォルダがGit管理されていなければ、そのプロジェクトでWorktreeを作ることはできません。

単発のメモやGit管理していない実験フォルダなら、Localで直接作業するほうが自然です。Worktreeを使うためだけに、目的のないGit管理を始める必要はありません。

一方、継続的に育てるプロジェクトで変更履歴を残し、複数タスクを並行させたいなら、GitリポジトリにしたうえでWorktreeを使う価値があります。Worktreeを使う前に、対象フォルダがGitリポジトリであることと、どのブランチを開始地点にするかを確認してください。

同じ設計図、別の作業場、最後に組み立てる

Worktreeの本質は、難しいGit用語ではなく、作業場所を分けることにあります。

Localはあなたが普段使う机、WorktreeはCodexや担当機能ごとに用意する別の机、Gitは全員が共有する履歴書庫です。同じブランチのHEADを設計図として始めても、各Worktreeにcheckoutされた未完成のファイルは途中で直接混ざりません。

ただし、全員が同じ名前付きブランチを同時にcheckoutして書き込むわけではありません。実行時に使うデータベース、ポート、外部サービスなども、Worktreeを作っただけでは自動隔離されません。そして、最後のマージ競合や部品同士の設計矛盾まで自動で消えるわけでもありません。

次のCodexタスクで迷ったら、判断はシンプルです。

• 今のフォルダへ変更がすぐ見えてよく、作業も一件だけならLocal
• checkout済みファイルを分けて別件を進めたいならCodex管理Worktree
• 同じ別作業場を長期間維持したいならPermanent Worktree

最後に、成果の統合と作業場所の移動だけは、はっきり分けて覚えてください。

成果を一つの履歴へ統合する
  → commit／branch／merge／Pull RequestなどのGit操作

同じ作業を別のcheckoutへ移して続ける
  → Handoff

Handoffは、複数成果を合体させる機能でも、mergeの代替でもありません。Worktreeで進めていた同じ作業をLocalへ移す、またはLocalからWorktreeへ戻して続けるための機能です。

つまりWorktreeとは、同じGitの履歴書庫を使いながら、checkoutされたファイルと作業状態を別の机へ分け、完成した成果はGit操作で統合する仕組みです。この一文が頭に入っていれば、Worktreeの便利さと限界を取り違えず、自分の作業に合った使い方を選べます。