Worktree

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 worktree、削除前のスナップショット、保存先を決める Settings ページで、Paneflow 上で 1 つのリポジトリの複数ブランチを並行して動かす。

2026年9月9日に更新

worktree を使うと、同じプロジェクトで複数のエージェントを互いに干渉させずに動かせます。それぞれがリポジトリの独自のチェックアウトを、独自のブランチ上に、独自の pane とエージェントセッションとともに持ち、リポジトリも worktree もコマンドもすべてあなたのマシンに留まります。

これらの worktree は Paneflow が作成し、削除します。削除する前には、未コミットの作業をスナップショットとして保存するので、後から復元できます。

worktree とは

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

用語

プロジェクトのチェックアウト: workspace として開いたリポジトリ。プロジェクトフォルダが指している場所です。
管理対象 worktree: そのチェックアウトから Paneflow が作成し、あなたの代わりに後始末する Git worktree。
スナップショット: worktree を削除する直前に、その未コミットの変更から Paneflow が作るコミット。何も失われません。

worktree を使う理由

あるエージェントに機能を作らせ、別のエージェントにバグを直させる。それぞれ独自のブランチで、プロジェクトのチェックアウトに触れません。
前面の作業に集中している間、長いタスクをバックグラウンドで続けられます。
結果は後で Review で、他の worktree と並べて、何もチェックアウトせずに読めます。

はじめに

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 トグル、開くエージェントの一覧。

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

Launch Pad には「New branch」欄と同じ「From」セレクトがあります。
タブのコンテキストメニューは、既存のタブに対して 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 と Review

Review は何もチェックアウトせずに worktree を読みます。ブランチか worktree を pane の端にドラッグすると、選んだ起点との diff を最大 6 つ並べて読めます。worktree を削除すると Review からも外れます。

よくある質問

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 を削除することはありません。