Worktrees

Worktrees lassen mehrere Agents am selben Projekt arbeiten, ohne dass sie sich in die Quere kommen. Jeder bekommt seinen eigenen Checkout des Repositories, auf seinem eigenen Branch, mit eigenen Panes und Agent-Sessions, während Repository, Worktrees und Befehle auf deinem Rechner bleiben.

Paneflow legt diese Worktrees an und entfernt sie wieder. Bevor es einen entfernt, sichert es die uncommitteten Änderungen als Snapshot, den du später wiederherstellen kannst.

Was ein Worktree ist

Worktrees gibt es nur für Projekte in einem Git-Repository, denn Paneflow nutzt darunter Git-Worktrees. Ein Worktree ist eine zweite Kopie ("Checkout") deines Repositories. Er hat seine eigene Kopie jeder Datei, teilt aber dieselben Metadaten (den Ordner .git) über Commits, Branches und Remotes. Genau das erlaubt, mehrere Branches gleichzeitig auszuchecken und zu bearbeiten.

Begriffe

• Projekt-Checkout: das Repository, das du als Workspace geöffnet hast, auf das dein Projektordner zeigt.
• Verwalteter Worktree: ein Git-Worktree, den Paneflow aus diesem Checkout erzeugt hat und für dich aufräumt.
• Snapshot: ein Commit, den Paneflow aus den uncommitteten Änderungen eines Worktrees macht, direkt bevor es ihn entfernt, damit nichts verloren geht.

Warum einen Worktree nutzen

• Ein Agent arbeitet an einem Feature, ein anderer behebt einen Bug, jeder auf seinem Branch, ohne den Projekt-Checkout zu stören.
• Eine lange Aufgabe läuft im Hintergrund weiter, während du im Vordergrund bleibst.
• Das Ergebnis liest du später in Review, neben anderen Worktrees, ohne etwas auszuchecken.

Erste Schritte

Worktrees brauchen ein Git-Repository. Stelle sicher, dass das geöffnete Projekt in einem liegt.

Ein Pane auf einem neuen Branch öffnen

1. Füge ein Pane hinzu. Die Palette "New pane" öffnet sich mit einer Branch-Zeile über der Liste der Agents.
2. Öffne die Branch-Zeile und wähle New branch….
3. Gib einen Branch-Namen ein, oder lass ihn leer, um detached zu starten.
4. Wähle unter from den Branch oder Commit, von dem es losgeht. Standard ist der Branch, auf dem dein Projekt steht.
5. Lass den Schalter Worktree an.
6. Wähle, womit geöffnet wird: ein Terminal, Claude Code, Codex, OpenCode oder ein selbst konfigurierter Launcher.

Paneflow erzeugt den Branch und seinen Worktree von der gewählten Basis, bindet den Tab an diesen Worktree und öffnet das Pane dort. Der Tab zeigt den Branch-Namen, und der Agent startet im Worktree-Verzeichnis.

Derselbe Ablauf existiert an drei weiteren Stellen:

• Das Launch Pad hat ein Feld "New branch" und dieselbe Auswahl "From".
• Das Kontextmenü eines Tabs bietet New branch… für einen bereits bestehenden Tab.
• paneflow up und Flows nehmen die Felder worktree und from; siehe Scripting.

Einen bestehenden Branch wiederverwenden

Wähle einen bestehenden Branch in der Branch-Zeile, oder tippe seinen Namen in "New branch…". Ist der Branch schon in einem Worktree ausgecheckt, verwendet Paneflow diesen Worktree. Ist er nirgends ausgecheckt, legt Paneflow einen Worktree dafür an. Die Basis "from" wird dann ignoriert, der Branch hat ja schon seine eigene Historie.

Git erlaubt, einen Branch nur an einer Stelle gleichzeitig auszuchecken. Paneflow kämpft nie gegen diese Regel: Es verwendet den bestehenden Checkout wieder, statt mit 'feature/a' is already used by worktree at … zu scheitern.

Detached starten, den Branch später benennen

Lass den Branch-Namen leer, und Paneflow legt einen Worktree detached an der gewählten Basis an, benannt <base>-<sha> nach dem Start-Commit. Das ist die richtige Wahl, wenn du noch nicht weißt, ob die Arbeit einen Branch verdient.

Wenn ja, klicke mit rechts auf den Tab und wähle Create branch here…. Paneflow führt git switch -c in diesem Worktree aus, deine uncommitteten Änderungen bleiben also genau, wo sie sind.

Stattdessen den Projekt-Checkout wechseln

Schalte Worktree im Formular "New branch…" aus, und Paneflow wechselt deinen Projekt-Checkout an Ort und Stelle auf den Branch, wie git switch -c, statt einen Worktree anzulegen. Das Pane öffnet im Repository-Root, und nichts kommt in die Liste der verwalteten Worktrees.

Nutze das, wenn du allein am Repository arbeitest und einen Branch ohne zweiten Ordner willst. Paneflow merkt sich deine letzte Wahl in worktrees.for_new_branches, der Schalter öffnet also so, wie du ihn gelassen hast.

Ein Checkout-Wechsel verschiebt die Dateien unter jedem Pane, das ihn benutzt, deshalb verweigert Paneflow den Wechsel, solange ein Agent in diesem Checkout arbeitet. Genau dafür gibt es Worktrees.

Wo Worktrees liegen

Paneflow legt verwaltete Worktrees unter ~/.paneflow/worktrees an (%USERPROFILE%\.paneflow\worktrees unter Windows), ein Unterverzeichnis pro Repository und ein Verzeichnis pro Branch:

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

In den Checkout selbst wird nichts geschrieben. Die Markierung, mit der Paneflow einen Worktree als seinen erkennt, liegt in den Git-Metadaten des Worktrees, git status bleibt also sauber, und die Markierung verschwindet mit dem Worktree.

Ändere die Wurzel in Settings > Worktrees oder mit worktrees.dir in paneflow.json. Die neue Wurzel gilt für danach angelegte Worktrees; Worktrees unter einer früheren Wurzel funktionieren weiter, wo sie sind, und bleiben gelistet.

Ignorierte lokale Dateien in neue Worktrees kopieren

Ein neuer Worktree startet aus einem Git-Checkout, verfolgte Dateien sind also schon da. Von Git ignorierte Dateien nicht, und ein Worktree braucht oft ein paar davon zum Laufen: .env, .env.local, eine lokale Secrets-Datei.

Lege eine Datei .worktreeinclude im Repository-Root an und liste die ignorierten Pfade, die kopiert werden sollen, einen pro Zeile, relativ zum Root. Verzeichnisse gehen auch, mit oder ohne abschließenden /, und # beginnt einen Kommentar.

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

Ohne die Datei kopiert Paneflow die obersten .env*-Dateien und AGENTS.override.md, sofern vorhanden. Eine im Worktree bereits vorhandene Datei wird nie überschrieben. Liste keine verfolgten Dateien; die bringt Git schon mit.

Aufräumen

Worktrees kosten Platz: Jeder trägt eigene Dateien, Abhängigkeiten und Build-Caches. Paneflow hält ihre Zahl von allein in Grenzen.

Standardmäßig behält Paneflow deine 15 neuesten verwalteten Worktrees. Ändere das Limit oder schalte das automatische Entfernen in Settings > Worktrees ab, oder mit worktrees.keep_limit und worktrees.auto_remove in paneflow.json.

Ein verwalteter Worktree wird automatisch entfernt, wenn:

• du den Workspace schließt, zu dem er gehört;
• Paneflow die ältesten kürzen muss, um unter dem Behalte-Limit zu bleiben.

Ein verwalteter Worktree wird nie automatisch entfernt, solange ein Tab in einem offenen Workspace ihn benutzt. Der Branch wird ebenfalls nie gelöscht: Einen Worktree zu entfernen entfernt nur den Checkout, deine Commits bleiben auf dem Branch.

Du kannst einen Worktree auch von Hand entfernen, in Settings > Worktrees oder über das Kontextmenü des Tabs. Paneflow entfernt nur Worktrees, die es selbst angelegt hat; Worktrees, die du mit git worktree add erzeugt hast, bleiben unangetastet.

Snapshots

Bevor Paneflow einen verwalteten Worktree entfernt, automatisch oder von Hand, sichert es dessen uncommittete Arbeit als Snapshot: Änderungen an verfolgten Dateien, neue Dateien und den Branch, auf dem der Worktree stand. Ein sauberer Worktree hinterlässt keinen Snapshot.

Snapshots sind gewöhnliche Git-Commits unter refs/paneflow/snapshots/ in deinem Repository. Sie berühren deine Branches nicht, werden nie gepusht, und du kannst sie mit git log refs/paneflow/snapshots/<name> ansehen, wenn du willst.

Settings > Worktrees listet sie unter "Snapshots":

• Restore legt den Worktree an seinem ursprünglichen Pfad neu an, auf demselben Branch, mit den gesicherten Änderungen wieder uncommitted, und kopiert deine .worktreeinclude-Dateien erneut.
• Delete verwirft den Snapshot endgültig.

Einen Worktree zu entfernen, dessen Änderungen du nicht mehr willst, ist mit Absicht ein Vorgang in zwei Schritten: entfernen, dann den Snapshot löschen.

Worktrees und Review

Review liest Worktrees, ohne etwas auszuchecken. Ziehe einen Branch oder Worktree auf eine Pane-Kante, um seinen Diff gegen die gewählte Basis zu lesen, bis zu sechs nebeneinander. Einen Worktree zu entfernen nimmt ihn auch aus Review.

Häufige Fragen

Kann ich steuern, wo Worktrees angelegt werden?

Ja. Setze die Wurzel in Settings > Worktrees oder mit worktrees.dir. ~ steht für dein Home-Verzeichnis, und PANEFLOW_HOME verschiebt den ganzen Ordner ~/.paneflow, Worktrees eingeschlossen.

Was passiert mit meiner Arbeit, wenn ein Worktree entfernt wird?

Deine Commits bleiben auf dem Branch. Uncommittete Änderungen landen in einem Snapshot, den du in Settings > Worktrees wiederherstellen kannst. Wähle den Branch erneut in der Palette "New pane", um einen frischen Worktree aus seinem committeten Stand zu bekommen.

Kann ich Arbeit zwischen einem Worktree und meinem Projekt-Checkout verschieben?

Committe oder stashe im Worktree, dann wechsle deinen Projekt-Checkout auf den Branch, entweder im Formular "New branch…" mit ausgeschaltetem Schalter Worktree oder mit git switch. Git verweigert das, solange der Branch noch im Worktree ausgecheckt ist, entferne diesen Worktree also zuerst in Settings > Worktrees.

Fasst Paneflow Worktrees an, die ich selbst angelegt habe?

Nein. Paneflow listet sie in der Branch-Zeile und öffnet Panes darin, entfernt aber nie einen Worktree, den es nicht selbst angelegt hat.

Siehe auch

• Konfigurationsreferenz: jeder Schlüssel worktrees.*.
• Review: Worktree-Diffs nebeneinander lesen.
• Scripting: worktree und from in paneflow up.
• Einstellungen: die Seite Worktrees.