worktree を使うと、同じプロジェクトで複数のエージェントを互いに干渉させずに 動かせます。それぞれがリポジトリの独自のチェックアウトを、独自のブランチ上に、 独自の pane とエージェントセッションとともに持ち、リポジトリも worktree も コマンドもすべてあなたのマシンに留まります。 これらの worktree は Paneflow が作成し、削除します。削除する前には、未コミット の作業をスナップショットとして保存するので、後から復元できます。 ## worktree とは worktree は Git リポジトリ内にあるプロジェクトでのみ使えます。Paneflow が内部 で Git worktree を使っているからです。worktree はリポジトリの 2 つ目のコピー （「チェックアウト」）です。すべてのファイルの独自のコピーを持ちながら、 コミット、ブランチ、リモートに関するメタデータ（`.git` フォルダ）は共有しま す。これにより、複数のブランチを同時にチェックアウトして作業できます。 ### 用語 - **プロジェクトのチェックアウト:** workspace として開いたリポジトリ。プロ ジェクトフォルダが指している場所です。 - **管理対象 worktree:** そのチェックアウトから Paneflow が作成し、あなたの 代わりに後始末する Git worktree。 - **スナップショット:** worktree を削除する直前に、その未コミットの変更から Paneflow が作るコミット。何も失われません。 ### worktree を使う理由 - あるエージェントに機能を作らせ、別のエージェントにバグを直させる。それぞ れ独自のブランチで、プロジェクトのチェックアウトに触れません。 - 前面の作業に集中している間、長いタスクをバックグラウンドで続けられます。 - 結果は後で [Review](/docs/review) で、他の worktree と並べて、何もチェック アウトせずに読めます。 ## はじめに worktree には Git リポジトリが必要です。開いたプロジェクトがリポジトリ内に あることを確認してください。 ### 新しいブランチで pane を開く 1. pane を追加します。「New pane」パレットが、エージェント一覧の上にブランチ 行を伴って開きます。 2. ブランチ行を開いて **New branch…** を選びます。 3. ブランチ名を入力するか、空のままにして detached で始めます。 4. **from** で起点となるブランチかコミットを選びます。デフォルトはプロジェク トが現在いるブランチです。 5. **Worktree** トグルはオンのままにします。 6. 何で開くかを選びます。ターミナル、Claude Code、Codex、OpenCode、または設 定済みの任意のランチャーです。 Paneflow は選んだ起点からブランチとその worktree を作り、タブをその worktree に結びつけ、そこで pane を開きます。タブにはブランチ名が表示され、エージェン トは worktree のディレクトリ内で起動します。
Paneflow の New pane パレットと New branch フォーム: ブランチ名の入力欄、from セレクト、Worktree トグル、開くエージェントの一覧。 Paneflow の New pane パレットと New branch フォーム: ブランチ名の入力欄、from セレクト、Worktree トグル、開くエージェントの一覧。
同じ流れは他の 3 か所にもあります。 - **Launch Pad** には「New branch」欄と同じ「From」セレクトがあります。 - タブのコンテキストメニューは、既存のタブに対して **New branch…** を提供し ます。 - `paneflow up` とフローは `worktree` と `from` フィールドを受け付けます。 [Scripting](/docs/scripting) を参照してください。 ### 既存のブランチを再利用する ブランチ行で既存のブランチを選ぶか、「New branch…」にその名前を入力します。 ブランチが既にどこかの worktree にチェックアウトされていれば、Paneflow はその worktree を再利用します。どこにもチェックアウトされていなければ、Paneflow が worktree を作ります。この場合「from」の起点は無視されます。ブランチには既に 独自の履歴があるからです。 Git はブランチを同時に 1 か所でしかチェックアウトできません。Paneflow はこの ルールに逆らわず、`'feature/a' is already used by worktree at …` で失敗する 代わりに既存のチェックアウトを再利用します。 ### detached で始めて、後からブランチ名を付ける ブランチ名を空にすると、Paneflow は選んだ起点で detached の worktree を作り、 起点コミットにちなんで `-` と名付けます。作業がブランチに値するか まだ分からないときに適した選択です。 値すると分かったら、タブを右クリックして **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 つのディレクトリで作ります。 ```text ~/.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 の一覧、スナップショットのセクション。 Paneflow の Settings > Worktrees ページ: worktree のルート、自動削除のトグル、保持上限、管理対象 worktree の一覧、スナップショットのセクション。
### 無視されたローカルファイルを新しい worktree にコピーする 新しい worktree は Git のチェックアウトから始まるので、追跡ファイルは既に揃っ ています。Git が無視するファイルはなく、worktree を動かすにはそのいくつかが 必要なことがよくあります。`.env`、`.env.local`、ローカルのシークレットファイ ルなどです。 リポジトリのルートに `.worktreeinclude` ファイルを置き、コピーする無視パスを ルートからの相対パスで 1 行に 1 つ列挙します。ディレクトリも末尾の `/` の有無 を問わず使え、`#` はコメントの開始です。 ```text # .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/` で確認できます。 **Settings > Worktrees** は「Snapshots」の下にそれらを一覧します。 - **Restore** は元のパスに、同じブランチで worktree を作り直し、保存した変更 を未コミットの状態で戻し、`.worktreeinclude` のファイルを再度コピーします。 - **Delete** はスナップショットを完全に破棄します。 変更がもう不要な worktree の削除は、意図的に 2 段階の操作になっています。削除 してから、スナップショットを消します。 ## worktree と Review [Review](/docs/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 を削除することはありません。 ## 関連ページ - [設定リファレンス](/docs/configuration/schema#worktrees): すべての `worktrees.*` キー。 - [Review](/docs/review): worktree の diff を並べて読む。 - [Scripting](/docs/scripting): `paneflow up` の `worktree` と `from`。 - [設定](/docs/settings): Worktrees ページ。