Worktrees

Git-Worktrees geben parallelen Aufgaben in Paneflow eigene versionierte Dateien und Branches. Jeder Checkout kann eigene Panes und Agenten-Sitzungen haben; die Repository-Historie bleibt auf deinem Rechner geteilt. Separate Checkouts verhindern keine Merge-Konflikte und isolieren keine Programme.

Paneflow erstellt und entfernt verwaltete Worktrees. Vor dem Entfernen speichert es uncommittete Dateien auf der Festplatte als Snapshot; speichere Editorpuffer zuerst. Ignorierte lokale Dateien und Geheimnisse benötigen eine gesonderte Behandlung, wie unten beschrieben.

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 aus den uncommitteten Dateien auf der Festplatte, direkt bevor Paneflow den Worktree entfernt. Ungespeicherte Editorpuffer und ignorierte Dateien sind von dieser Garantie nicht umfasst.

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.
• Den Diff liest du im Changes-Tab der Sitzung, ohne deinen Projekt-Checkout anzufassen.

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 zwei weiteren Stellen:

• 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.

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.

Zwei Aufgaben, dann eine Integration

Starte in Paneflow 0.17.4 von einer committeten Basis in einem Wegwerfprojekt. Nutze New branch... wie oben mit aktiviertem Worktree:

1. Erstelle feat/api-validation für die Aufgabe und test/api-validation für Tests von derselben Basis. Prüfe Pfad und Branch vor jedem Agentenstart.
2. Definiere Dateizuständigkeiten und getrennte Serverports. Installiere Abhängigkeiten im passenden Checkout. Uncommittete Änderungen im Projektcheckout gelangen nicht als versionierte Dateien in den neuen Worktree; committe die benötigte Basis vorher.
3. Speichere, lies Changes gegenüber dem jeweiligen HEAD, committe und prüfe den gesamten Branch-Diff mit Git. Changes ist kein Merge-Base-Review.
4. Integriere geprüfte Commits im gewählten Integrationscheckout, löse Konflikte und führe die passenden Tests zusammen aus. Entferne Checkouts erst, wenn nützliche Arbeit gesichert ist.

Historie, Remotes und Branchreferenzen bleiben geteilt. Ports, Datenbanken, Netzwerk und Benutzerrechte sind nicht isoliert. .worktreeinclude kann lokale Geheimnisse kopieren; wähle die Dateien bewusst. Ein Worktree ist keine Sicherheitssandbox.

Offener Branch, Projekt ohne Git oder ungespeicherter Editor

Ein bereits ausgecheckter Branch nutzt seinen vorhandenen Checkout erneut; es entsteht keine zweite unabhängige Kopie. Prüfe den Pfad zuerst. Projekte ohne Git haben keine verwalteten Git-Worktrees; nutze ihr Verzeichnis oder initialisiere Git bewusst.

Speichere oder verwirf Editorpuffer ausdrücklich vor Wechsel oder Entfernung. Snapshots lesen Festplattendateien, keinen ungespeicherten Text. Ein Wechsel des Projektcheckouts wird auch während aktiver Agentenarbeit verweigert. Verweigert Git den Wechsel wegen drohender Überschreibungen, sichere die Dateien und behebe die Ursache, ohne eine Bereinigung zu erzwingen.

Siehe Changes zum Review-Umfang und Files zu Speicherkonflikten.

Siehe auch

• Konfigurationsreferenz: jeder Schlüssel worktrees.*.
• Scripting: worktree und from in paneflow up.
• Einstellungen: die Seite Worktrees.