Worktrees

Q: worktree の作成場所を指定できますか？

はい。Settings > Worktrees か worktrees.dir でルートを設定します。~ はホー ムディレクトリに展開され、PANEFLOW_HOME は worktree を含む ~/.paneflow ディ レクトリ全体を移動します。

Q: worktree とプロジェクトのチェックアウトの間で作業を移せますか？

worktree でコミットか stash をしてから、プロジェクトのチェックアウトをそのブ ランチに切り替えます。Worktree トグルをオフにした「New branch…」フォームか、 git switch を使います。ブランチがまだ worktree にチェックアウトされている間 は Git が拒否するので、先に Settings > Worktrees からその worktree を削除して ください。

Q: 自分で作った worktree に Paneflow は触れますか？

いいえ。Paneflow はブランチ行にそれらを表示し、そこで pane を開きますが、自分 が作っていない worktree を削除することはありません。

独立した Git checkout を作成・再利用し、変更を確認してブランチを統合します。Worktree 管理、スナップショット、共有リソースの制限を説明します。

2026年10月1日に更新

Git worktree は Paneflow の並列タスクに独立した追跡ファイルとブランチを与えます。各 checkout はペインとエージェントセッションを持てますが、リポジトリ履歴はマシン上で共有します。Checkout の分離はマージ競合をなくさず、動作中のプログラムも隔離しません。

Paneflow は管理対象 worktree を作成・削除します。削除前のスナップショットはディスク上の未コミットファイルを読みます。先にエディタの buffer を保存してください。無視されたローカルファイルと秘密情報は別途扱う必要があります。

worktree とは

worktree は Git リポジトリ内にあるプロジェクトでのみ使えます。Paneflow が内部で Git worktree を使っているからです。worktree はリポジトリの 2 つ目のコピー（「チェックアウト」）です。すべてのファイルの独自のコピーを持ちながら、コミット、ブランチ、リモートに関するメタデータ（.git フォルダ）は共有します。これにより、複数のブランチを同時にチェックアウトして作業できます。

用語

プロジェクトのチェックアウト: workspace として開いたリポジトリ。プロジェクトフォルダが指している場所です。
管理対象 worktree: そのチェックアウトから Paneflow が作成し、あなたの代わりに後始末する Git worktree。
スナップショット: worktree を削除する直前に、ディスク上の未コミットのファイルから作るコミット。未保存のエディタ buffer と無視されたファイルはこの保証の対象外です。

worktree を使う理由

あるエージェントに機能を作らせ、別のエージェントにバグを直させる。それぞれ独自のブランチで、プロジェクトのチェックアウトに触れません。
前面の作業に集中している間、長いタスクをバックグラウンドで続けられます。
diff はセッションの Changes タブで、プロジェクトの checkout に触れずに読めます。

はじめに

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

新しいブランチで pane を開く

pane を追加します。「New pane」パレットが、エージェント一覧の上にブランチ行を伴って開きます。
ブランチ行を開いて New branch… を選びます。
ブランチ名を入力するか、空のままにして detached で始めます。
from で起点となるブランチかコミットを選びます。デフォルトはプロジェクトが現在いるブランチです。
Worktree トグルはオンのままにします。
何で開くかを選びます。ターミナル、Claude Code、Codex、OpenCode、または設定済みの任意のランチャーです。

Paneflow は選んだ起点からブランチとその worktree を作り、タブをその worktree に結びつけ、そこで pane を開きます。タブにはブランチ名が表示され、エージェントは worktree のディレクトリ内で起動します。

Paneflow の New pane パレットと New branch フォーム: ブランチ名の入力欄、from セレクト、Worktree トグル、開くエージェントの一覧。

同じ流れは他の 2 か所にもあります。

タブのコンテキストメニューは、既存のタブに対して New branch… を提供します。
paneflow up とフローは worktree と from フィールドを受け付けます。 Scripting を参照してください。

既存のブランチを再利用する

ブランチ行で既存のブランチを選ぶか、「New branch…」にその名前を入力します。ブランチが既にどこかの worktree にチェックアウトされていれば、Paneflow はその worktree を再利用します。どこにもチェックアウトされていなければ、Paneflow が worktree を作ります。この場合「from」の起点は無視されます。ブランチには既に独自の履歴があるからです。

Git はブランチを同時に 1 か所でしかチェックアウトできません。Paneflow はこのルールに逆らわず、'feature/a' is already used by worktree at … で失敗する代わりに既存のチェックアウトを再利用します。

detached で始めて、後からブランチ名を付ける

ブランチ名を空にすると、Paneflow は選んだ起点で detached の worktree を作り、起点コミットにちなんで <base>-<sha> と名付けます。作業がブランチに値するかまだ分からないときに適した選択です。

値すると分かったら、タブを右クリックして Create branch here… を選びます。 Paneflow はその worktree 内で git switch -c を実行するので、未コミットの変更はそのままの場所に残ります。

代わりにプロジェクトのチェックアウトを切り替える

「New branch…」フォームで Worktree トグルをオフにすると、Paneflow は worktree を作る代わりに、git switch -c と同じようにプロジェクトのチェックアウトをその場でブランチに切り替えます。pane はリポジトリのルートで開き、管理対象の一覧には何も追加されません。

リポジトリで一人で作業していて、2 つ目のフォルダなしにブランチが欲しいときに使ってください。Paneflow は最後の選択を worktrees.for_new_branches に記憶するので、トグルは前回の状態で開きます。

チェックアウトの切り替えは、それを使うすべての pane の足元でファイルを動かします。そのため、そのチェックアウトでエージェントが作業中の間、Paneflow は切り替えを拒否します。worktree はまさにそのための仕組みです。

worktree の保存場所

Paneflow は管理対象 worktree を ~/.paneflow/worktrees（Windows では %USERPROFILE%\.paneflow\worktrees）配下に、リポジトリごとに 1 つのサブディレクトリ、ブランチごとに 1 つのディレクトリで作ります。

~/.paneflow/worktrees/
  paneflow-05926cc4/
    feat-agents-browser/
    fix-login/

チェックアウト自体には何も書き込みません。Paneflow が自分の worktree だと判断するためのマーカーは worktree 自身の Git メタデータ内にあるので、git status はきれいなままで、マーカーは worktree とともに消えます。

ルートは Settings > Worktrees か、paneflow.json の worktrees.dir で変更できます。新しいルートはそれ以降に作る worktree に適用され、以前のルートで作った worktree はそのまま動き、一覧にも残ります。

Paneflow の Settings > Worktrees ページ: worktree のルート、自動削除のトグル、保持上限、管理対象 worktree の一覧、スナップショットのセクション。

無視されたローカルファイルを新しい worktree にコピーする

新しい worktree は Git のチェックアウトから始まるので、追跡ファイルは既に揃っています。Git が無視するファイルはなく、worktree を動かすにはそのいくつかが必要なことがよくあります。.env、.env.local、ローカルのシークレットファイルなどです。

リポジトリのルートに .worktreeinclude ファイルを置き、コピーする無視パスをルートからの相対パスで 1 行に 1 つ列挙します。ディレクトリも末尾の / の有無を問わず使え、# はコメントの開始です。

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

このファイルがない場合、Paneflow は最上位の .env* ファイルと AGENTS.override.md（存在すれば）をコピーします。worktree に既にあるファイルは上書きしません。追跡ファイルは列挙しないでください。Git が既に持ってきます。

後始末

worktree はディスクを消費します。それぞれが独自のファイル、依存関係、ビルドキャッシュを抱えるからです。Paneflow はその数を自動で妥当な範囲に保ちます。

デフォルトでは、Paneflow は最新の管理対象 worktree を 15 個保持します。上限の変更や自動削除の無効化は Settings > Worktrees で、または paneflow.json の worktrees.keep_limit と worktrees.auto_remove で行えます。

管理対象 worktree が自動的に削除されるのは次のときです。

それが属する workspace を閉じたとき
保持上限に収めるために Paneflow が古いものを整理する必要があるとき

開いている workspace のタブが使っている間は、管理対象 worktree が自動削除されることはありません。ブランチも決して削除されません。worktree の削除はチェックアウトを取り除くだけで、コミットはブランチに残ります。

Settings > Worktrees かタブのコンテキストメニューから、手動で worktree を削除することもできます。Paneflow が削除するのは自分で作った worktree だけで、 git worktree add であなたが作ったものには触れません。

スナップショット

管理対象 worktree を削除する前に、自動でも手動でも、Paneflow はその未コミットの作業をスナップショットとして保存します。追跡ファイルの編集、新規ファイル、 worktree がいたブランチが対象です。きれいな worktree はスナップショットを残しません。

スナップショットはリポジトリ内の refs/paneflow/snapshots/ 配下にある通常の Git コミットです。ブランチには触れず、push されることもなく、必要なら git log refs/paneflow/snapshots/<name> で確認できます。

Settings > Worktrees は「Snapshots」の下にそれらを一覧します。

Restore は元のパスに、同じブランチで worktree を作り直し、保存した変更を未コミットの状態で戻し、.worktreeinclude のファイルを再度コピーします。
Delete はスナップショットを完全に破棄します。

変更がもう不要な worktree の削除は、意図的に 2 段階の操作になっています。削除してから、スナップショットを消します。

よくある質問

worktree の作成場所を指定できますか？

はい。Settings > Worktrees か worktrees.dir でルートを設定します。~ はホームディレクトリに展開され、PANEFLOW_HOME は worktree を含む ~/.paneflow ディレクトリ全体を移動します。

worktree が削除されると作業はどうなりますか？

コミットはブランチに残ります。未コミットの変更はスナップショットに入り、 Settings > Worktrees から復元できます。「New pane」パレットでそのブランチを再び選ぶと、コミット済みの状態から新しい worktree が作られます。

worktree とプロジェクトのチェックアウトの間で作業を移せますか？

worktree でコミットか stash をしてから、プロジェクトのチェックアウトをそのブランチに切り替えます。Worktree トグルをオフにした「New branch…」フォームか、 git switch を使います。ブランチがまだ worktree にチェックアウトされている間は Git が拒否するので、先に Settings > Worktrees からその worktree を削除してください。

自分で作った worktree に Paneflow は触れますか？

いいえ。Paneflow はブランチ行にそれらを表示し、そこで pane を開きますが、自分が作っていない worktree を削除することはありません。

二つのタスクから一つの統合へ

Paneflow 0.17.4 と使い捨て Git プロジェクトで、コミット済みの基準から始めます。上記 New branch... の手順で Worktree を有効にします。

同じ基準から feat/api-validation と test/api-validation を作り、実装とテストに分けます。エージェント起動前にパスとブランチを確認します。
ファイルの担当を明示し、開発サーバーには別のポートを使います。依存関係は対応する checkout に入れます。主 checkout の未コミット変更は新 worktree の追跡ファイルには入りません。両タスクで必要なら基準を先にコミットしてください。
保存後に各 checkout の HEAD に対する Changes を確認し、コミットして Git でブランチ全体を確認します。Changes は merge-base レビューではありません。
選んだ統合 checkout にレビュー済みコミットを統合し、競合を解決して関連テストを実行します。必要な作業を残すまで checkout は削除しません。

履歴、remote、ブランチ参照は共有します。ポート、データベース、ネットワーク、ユーザー権限は隔離されません。.worktreeinclude はローカルの秘密情報もコピーできるため、タスクごとに選んでください。Worktree はセキュリティ sandbox ではありません。

使用中のブランチ、非 Git プロジェクト、未保存編集

チェックアウト済みブランチは既存 checkout を再利用し、独立コピーを作りません。分離されていると考える前にパスを確認します。非 Git プロジェクトには管理対象 worktree の操作はなく、現在のディレクトリを使うか意図的に Git を初期化します。

切り替え・削除前にエディタ buffer を保存するか、意図的に破棄します。スナップショットは未保存テキストを読みません。主 checkout でエージェントが作業中の切り替えも拒否されます。Git が上書きの危険で拒否したらファイルを保全して原因を解決し、強制クリーンアップを使わないでください。

レビュー範囲は Changes、保存競合は Filesを参照してください。