ワークツリー¶

ChatGPT デスクトップアプリでは、ワークツリーを使うと、同じプロジェクト内で互いに干渉することなく、複数の独立したチャットを Codex で実行できます。Git リポジトリでは、スケジュール済みタスクを専用のバックグラウンドワークツリーで実行できるため、進行中の作業と競合しません。バージョン管理されていないプロジェクトでは、スケジュール済みタスクはプロジェクトディレクトリで直接実行されます。また、手動でワークツリー内のチャットを開始し、Handoff を使って Local と Worktree の間でチャットを移動することもできます。

ワークツリーは、ChatGPT デスクトップアプリの Codex でのみ利用できます。ワークツリーでチャットを開始する前に、Codex を選択してください。

ワークツリーとは¶

ワークツリーは、内部で Git ワークツリーを使用するため、Git リポジトリの一部であるプロジェクトでのみ機能します。ワークツリーを使うと、リポジトリの 2 つ目のコピー（「チェックアウト」）を作成できます。各ワークツリーにはリポジトリ内のすべてのファイルの独自のコピーがありますが、コミットやブランチなどに関する同じメタデータ（.git フォルダー）を共有します。これにより、複数のブランチを並行してチェックアウトし、作業できます。

用語¶

Local checkout: 作成したリポジトリです。ChatGPT デスクトップアプリでは、単に Local と呼ばれることもあります。
Worktree: ChatGPT デスクトップアプリでローカルチェックアウトから作成された Git ワークツリーです。
Handoff: Local と Worktree の間でチャットを移動するフローです。Codex は、両者の間で安全に作業を移動するために必要な Git 操作を処理します。

ワークツリーを使う理由¶

現在の Local の設定に影響を与えず、Codex と並行して作業できます。
フォアグラウンドの作業に集中しながら、バックグラウンドの作業をキューに追加できます。
確認、テスト、またはより直接的な共同作業を行う準備ができたら、後でチャットを Local に移動できます。

はじめに¶

ワークツリーには Git リポジトリが必要です。選択したプロジェクトが Git リポジトリ内にあることを確認してください。

「Worktree」を選択する

新しいチャットビューで、コンポーザーの下にある Worktree を選択します。オプションで、ワークツリーのセットアップスクリプトを実行するためのローカル環境を選択できます。
開始ブランチを選択する

コンポーザーの下で、ワークツリーのベースにする Git ブランチを選択します。main / master ブランチ、フィーチャーブランチ、またはステージされていないローカル変更を含む現在のブランチを選択できます。
プロンプトを送信する

プロンプトを送信すると、Codex は選択したブランチに基づいて Git ワークツリーを作成します。デフォルトでは、Codex は "detached HEAD" で作業します。
作業を続ける場所を選択する

準備ができたら、ワークツリーで直接作業を続けるか、チャットをローカルチェックアウトにハンドオフできます。Local への、または Local からのハンドオフでは、チャットとコードが移動するため、もう一方のチェックアウトで作業を続けられます。

Local と Worktree の間で作業する¶

ワークツリーの外観や操作感は、ローカルチェックアウトとほぼ同じです。違いは、ワークフローの中での位置付けです。Local はフォアグラウンド、Worktree はバックグラウンドだと考えることができます。Handoff を使うと、両者の間でチャットを移動できます。

内部では、Handoff が 2 つのチェックアウト間で安全に作業を移動するために必要な Git 操作を処理します。これは、Git ではブランチを一度に 1 か所でしかチェックアウトできないため重要です。ワークツリーでブランチをチェックアウトすると、同時にローカルチェックアウトでそのブランチをチェックアウトすることはできません。逆の場合も同様です。

実際には、一般的な方法が 2 つあります。

ワークツリーだけで作業する。依存関係やツールをローカル環境のセットアップスクリプトでインストールしているため、ワークツリー上で変更を直接検証できる場合に適しています。
チャットを Local にハンドオフする。通常の IDE で変更を確認したい場合や、アプリのインスタンスを 1 つしか実行できない場合など、チャットをフォアグラウンドに移したいときに使います。

オプション 1: ワークツリーで作業する¶

変更をワークツリーだけに保持して作業したい場合は、チャットヘッダーの **Create branch here** ボタンを使って、ワークツリーをブランチに変換します。ここから変更をコミットし、ブランチをリモートリポジトリにプッシュして、GitHub でプルリクエストを作成できます。ヘッダーの「Open」ボタンを使って IDE でワークツリーを開いたり、統合ターミナルを使ったり、ワークツリーディレクトリから必要なその他の操作を行ったりできます。

ワークツリーでブランチを作成すると、ローカルチェックアウトを含む他のワークツリーではそのブランチをチェックアウトできないことに注意してください。

オプション 2: チャットを Local にハンドオフする¶

チャットをフォアグラウンドに移したい場合は、チャットヘッダーで **Hand off** を選択し、**Local** に移動します。この方法は、使い慣れた IDE ウィンドウで変更を確認したい場合、既存の開発サーバーを実行したい場合、または日常的に使用している同じ環境で作業を検証したい場合に適しています。 Codex は、ワークツリーとローカルチェックアウトの間でチャットを安全に移動するために必要な Git の手順を処理します。各チャットには、時間が経過しても同じ関連ワークツリーが保持されます。後でチャットをワークツリーに戻すと、Codex は同じバックグラウンド環境に戻すため、中断したところから再開できます。

逆方向に移動することもできます。すでに Local で作業していてフォアグラウンドを空けたい場合は、Hand off を使ってチャットをワークツリーに移動します。これは、別のローカル作業に注意を戻す間、Codex にバックグラウンドで作業を続けさせたい場合に便利です。

Handoff は Git 操作を使用するため、.gitignore ファイルに含まれるファイルは、Codex が .worktreeinclude を使ってローカル管理ワークツリーにコピーしない限り、チャットと一緒には移動しません。

詳細¶

Codex 管理ワークツリーと永続ワークツリー¶

デフォルトでは、チャットは Codex 管理ワークツリーを使用します。これらは軽量で使い捨てのものとして設計されています。通常、Codex 管理ワークツリーは 1 つのチャット専用であり、後でチャットをそこに戻すと、Codex は同じワークツリーに戻します。

長期間使用する環境が必要な場合は、サイドバーのプロジェクトにある 3 点メニューから永続ワークツリーを作成します。これにより、独自のプロジェクトとして新しい永続ワークツリーが作成されます。永続ワークツリーは自動的に削除されず、同じワークツリーから複数のチャットを開始できます。

Codex によるワークツリーの管理方法¶

Codex は $CODEX_HOME/worktrees にワークツリーを作成します。開始コミットは、チャット開始時に選択したブランチの HEAD コミットです。ローカル変更を含むブランチを選択した場合、Codex はコミットされていない変更もワークツリーに適用します。ワークツリーはブランチとしてチェックアウトされません。detached HEAD 状態になります。これにより、Codex はブランチを汚染せずに複数のワークツリーを作成できます。

無視されたローカルファイルを管理ワークツリーにコピーする¶

ローカルの Codex 管理ワークツリーは Git チェックアウトから開始するため、追跡対象のファイルはすでに存在します。新しいワークツリーに必要なローカルセットアップファイルをリポジトリで無視している場合は、リポジトリのルートに .worktreeinclude ファイルを追加し、Codex が管理ワークツリーを作成するときにコピーする無視対象のパスまたは .gitignore 形式のパターンを一覧にします。

これは、Git が意図的に無視するファイル（.env、.env.local、config/secrets.json など）に使用します。Codex は .worktreeinclude に一致する無視対象ファイルのみをコピーします。Git が追跡していないその他のローカルファイルはコピーしません。追跡対象のファイルは一覧に含めないでください。

Codex は無視対象の AGENTS.override.md を自動的にローカル管理ワークツリーにコピーするため、.worktreeinclude に一覧化する必要はありません。

# .worktreeinclude
.env
.env.local
config/secrets.json

Codex はソースシンボリックリンクをスキップし、新しいチェックアウトにすでに存在するファイルを上書きしません。この動作は、ChatGPT デスクトップアプリが管理するローカルワークツリーに適用されます。リモートワークツリーや、コマンドラインから自分で作成した Git ワークツリーには適用されません。

ブランチの制限¶

Codex がワークツリーで作業を終え、Create branch here を使って feature/a ブランチを作成したとします。次に、それをローカルチェックアウトで試したいとします。そのブランチをチェックアウトしようとすると、次のエラーが表示されます。

fatal: 'feature/a' is already used by worktree at '<WORKTREE_PATH>'

これを解決するには、ワークツリーで feature/a 以外のブランチをチェックアウトする必要があります。

ローカルでブランチをチェックアウトする予定がある場合は、同じブランチを両方の場所で同時にチェックアウトしようとするのではなく、Handoff を使ってチャットを Local に移動してください。

Git では、ブランチは単一の可変参照（refs/heads/<name>）を表し、その意味は「ワーキングツリーで現在チェックアウトされている状態」であるため、同じブランチを一度に複数のワークツリーでチェックアウトすることはできません。

ブランチがチェックアウトされると、Git はその HEAD をワークツリーが所有するものとして扱い、コミット、リセット、リベース、マージなどの操作によって、その参照が明確かつ直列化された方法で進むことを想定します。複数のワークツリーで同じブランチを同時にチェックアウトできるようにすると、どのワークツリーの操作がブランチ参照を更新するのかについて曖昧さや競合状態が生じ、コミットの消失、インデックスの不整合、競合解決方法の不明確さにつながる可能性があります。

Git は「1 ワークツリーにつき 1 ブランチ」というルールを適用することで、各ブランチに単一の信頼できる作業コピーがあることを保証しながら、他のワークツリーから detached HEAD や個別のブランチを通じて同じコミットを安全に参照できるようにしています。

ワークツリーのクリーンアップ¶

ワークツリーは大量のディスク容量を使用することがあります。それぞれに独自のリポジトリファイル、依存関係、ビルドキャッシュなどがあるためです。その結果、ChatGPT デスクトップアプリはワークツリーの数を適切な上限内に保とうとします。

デフォルトでは、Codex は最新の Codex 管理ワークツリーを 15 個保持します。設定でこの上限を変更したり、自分でディスク使用量を管理する場合は自動削除を無効にしたりできます。

Codex は、重要なワークツリーが削除されないように努めます。Codex 管理ワークツリーは、次の場合には自動的に削除されません。

ピン留めされたチャットが関連付けられている
チャットがまだ進行中である
ワークツリーが永続ワークツリーである

Codex 管理ワークツリーは、次の場合に自動的に削除されます。

関連付けられたチャットをアーカイブした
設定した上限内に収めるため、Codex が古いワークツリーを削除する必要がある

Codex 管理ワークツリーを削除する前に、Codex はそのワークツリー上の作業のスナップショットを保存します。ワークツリーが削除された後にチャットを開くと、復元するオプションが表示されます。

よくある質問¶

はい。Codex はデフォルトで $CODEX_HOME/worktrees の下に管理ワークツリーを作成します。別の場所を選択するには、Settings > Worktrees を開き、Worktree root を変更します。

はい。チャットヘッダーの Hand off を使って、ローカルチェックアウトとワークツリーの間でチャットを移動できます。Codex は、環境間でチャットを安全に移動するために必要な Git 操作を処理します。後でチャットをワークツリーに戻すと、Codex は同じ関連ワークツリーに戻します。

基盤となるワークツリーディレクトリが削除されても、チャットは履歴に残ることがあります。Codex 管理ワークツリーの場合、Codex はワークツリーを削除する前にスナップショットを保存し、関連付けられたチャットを再度開いたときに復元を提案します。永続ワークツリーは、関連するチャットをアーカイブしても自動的には削除されません。