Mit Worktrees kann Codex mehrere unabhängige Chats im selben Projekt parallel ausführen, ohne dass sie sich gegenseitig stören. Das Repository und der Worktree bleiben auf dem Computer oder in der Remote-Entwicklungsumgebung, wo das Projekt liegt. Auch die Befehle werden dort ausgeführt. Du kannst direkt in der ChatGPT-Desktop-App arbeiten. Mit Codex in der mobilen ChatGPT-App kannst du Worktree-Chats auf einem verbundenen Computer starten, die Arbeit steuern, Aktionen genehmigen und Ergebnisse überprüfen.
In Git-Repositorys können geplante Aufgaben im Hintergrund in eigenen Worktrees laufen, ohne deine laufende Arbeit zu stören. In Projekten ohne Versionsverwaltung laufen geplante Aufgaben direkt im Projektverzeichnis. Du kannst Chats auch manuell in einem Worktree starten und sie per Übergabe zwischen „Lokal“ und „Worktree“ verschieben.
Worktrees laufen nicht lokal auf deinem Smartphone. Mit der mobilen ChatGPT-App steuerst du Codex auf deinem verbundenen Computer oder in der Remote-Entwicklungsumgebung, die dieser Computer nutzt. Dort bleiben auch das Repository und der Worktree. Die folgenden Anweisungen für die Desktop-App gelten für den verbundenen Computer.
Was ist ein Worktree?
Worktrees funktionieren nur in Projekten, die zu einem Git-Repository gehören, da Codex dafür Git-Worktrees nutzt. Mit einem Worktree kannst du eine zweite Arbeitskopie („Checkout“) deines Repositorys erstellen. Jeder Worktree hat eine eigene Kopie jeder Datei im Repository. Die Metadaten zu Commits, Branches und anderen Git-Objekten (Ordner .git) nutzen alle Worktrees gemeinsam. So kannst du mehrere Branches gleichzeitig auschecken und parallel daran arbeiten.
Begriffe
- Lokaler Checkout: Das Repository, das du erstellt hast. In der ChatGPT-Desktop-App heißt es teilweise einfach Lokal.
- Worktree: Ein Git-Worktree, den die ChatGPT-Desktop-App aus deinem lokalen Checkout erstellt hat.
- Übergabe: Der Vorgang, mit dem du einen Chat zwischen „Lokal“ und „Worktree“ verschiebst. Codex übernimmt die Git-Operationen, die nötig sind, um deine Arbeit sicher zwischen den beiden Checkouts zu übertragen.
Warum einen Worktree verwenden?
- Arbeite parallel mit Codex, ohne dein aktuelles Setup unter „Lokal“ zu verändern.
- Stelle Aufgaben für die Bearbeitung im Hintergrund in die Warteschlange, während du dich auf deine Arbeit im Vordergrund konzentrierst.
- Verschiebe einen Chat später nach „Lokal“, wenn du die Änderungen prüfen, testen oder gemeinsam mit anderen direkt daran arbeiten möchtest.
Erste Schritte
Worktrees setzen ein Git-Repository voraus. Vergewissere dich, dass das ausgewählte Projekt in einem Git-Repository liegt.
-
„Worktree“ auswählen
Wähle in der Ansicht für einen neuen Chat unter dem Editor Worktree aus. Optional kannst du eine lokale Umgebung auswählen, um Setup-Skripte für den Worktree auszuführen.
-
Ausgangsbranch auswählen
Wähle unter dem Editor den Git-Branch aus, auf dem der Worktree basieren soll. Das kann dein
main- odermaster-Branch sein, ein Feature-Branch oder dein aktueller Branch mit lokalen Änderungen, die noch nicht im Staging-Bereich liegen. -
Prompt absenden
Sende deinen Prompt ab. Codex erstellt dann einen Git-Worktree auf Basis des ausgewählten Branches. Standardmäßig arbeitet Codex mit einem losgelösten HEAD.
-
Entscheiden, wo du weiterarbeiten möchtest
Du kannst direkt im Worktree weiterarbeiten oder den Chat an deinen lokalen Checkout übergeben. Bei einer Übergabe nach „Lokal“ oder von dort zum Worktree verschiebt Codex deinen Chat und deinen Code, sodass du im anderen Checkout weiterarbeiten kannst.
Zwischen „Lokal“ und „Worktree“ wechseln
In einem Worktree arbeitest du ähnlich wie in deinem lokalen Checkout. Der Unterschied liegt darin, wie du die beiden einsetzt. Stell dir „Lokal“ als Vordergrund und „Worktree“ als Hintergrund vor. Per Übergabe kannst du einen Chat zwischen beiden verschieben.
Bei der Übergabe führt Codex die Git-Operationen aus, die nötig sind, um deine Arbeit sicher von einem Checkout in den anderen zu verschieben. Das ist wichtig, denn in Git kann ein Branch immer nur an einer Stelle ausgecheckt sein. Wenn du einen Branch in einem Worktree auscheckst, kannst du ihn nicht gleichzeitig in deinem lokalen Checkout auschecken. Das gilt auch umgekehrt.
In der Praxis hast du zwei gängige Möglichkeiten:
- Ausschließlich im Worktree arbeiten. Das bietet sich an, wenn du Änderungen direkt im Worktree überprüfen kannst, etwa weil du die nötigen Abhängigkeiten und Tools mit einem Setup-Skript für die lokale Umgebung installiert hast.
- Den Chat an „Lokal“ übergeben. Wähle diesen Weg, wenn du den Chat in den Vordergrund holen möchtest, etwa weil du Änderungen in deiner gewohnten IDE prüfen möchtest oder nur eine Instanz deiner App ausführen kannst.
Option 1: Im Worktree arbeiten
Wenn du mit deinen Änderungen ausschließlich im Worktree bleiben möchtest, erstelle dort über die Schaltfläche Branch hier erstellen im Chatkopf einen Branch.
Anschließend kannst du deine Änderungen committen, den Branch in dein Remote-Repository pushen und auf GitHub einen Pull Request öffnen.
Über die Schaltfläche „Öffnen“ im Chatkopf kannst du den Worktree in deiner IDE öffnen. Du kannst auch das integrierte Terminal nutzen oder andere Arbeiten direkt im Worktree-Verzeichnis erledigen.
Wenn du einen Branch in einem Worktree erstellst, kannst du ihn nicht gleichzeitig in einem anderen Worktree auschecken. Das gilt auch für deinen lokalen Checkout.
Option 2: Einen Chat an „Lokal“ übergeben
Um einen Chat in den Vordergrund zu holen, wähle im Chatkopf Übergeben aus und verschiebe den Chat nach Lokal.
Das bietet sich an, wenn du die Änderungen in deinem gewohnten IDE-Fenster ansehen, deinen vorhandenen Entwicklungsserver starten oder die Ergebnisse in deiner alltäglichen Entwicklungsumgebung überprüfen möchtest.
Codex übernimmt die Git-Schritte, die nötig sind, um den Chat sicher zwischen dem Worktree und deinem lokalen Checkout zu verschieben.
Jeder Chat bleibt demselben Worktree zugeordnet. Wenn du den Chat später wieder an einen Worktree übergibst, bringt Codex ihn in dieselbe Hintergrundumgebung zurück. So kannst du dort weitermachen, wo du aufgehört hast.
Die Übergabe funktioniert auch in die andere Richtung. Wenn du bereits unter „Lokal“ arbeitest und den Vordergrund freigeben möchtest, verschiebe den Chat über Übergeben in einen Worktree. So kann Codex im Hintergrund weiterarbeiten, während du dich lokal wieder einer anderen Aufgabe widmest.
Da die Übergabe Git-Operationen nutzt, werden Dateien, die Git aufgrund deiner .gitignore ignoriert, nicht mit dem Chat verschoben. Eine Ausnahme gilt, wenn Codex sie mithilfe von .worktreeinclude in einen lokalen, von Codex verwalteten Worktree kopiert.
Weiterführende Informationen
Von Codex verwaltete Worktrees
Standardmäßig verwenden Chats einen von Codex verwalteten Worktree. Diese Worktrees lassen sich ohne großen Aufwand nutzen und wieder verwerfen. In der Regel ist ein von Codex verwalteter Worktree für einen einzigen Chat vorgesehen. Wenn du den Chat später wieder dorthin übergibst, bringt Codex ihn in denselben Worktree zurück.
So verwaltet Codex deine Worktrees
Codex erstellt Worktrees unter $CODEX_HOME/worktrees. Der Ausgangspunkt ist der HEAD-Commit des Branches, den du beim Start des Chats auswählst. Wählst du einen Branch mit lokalen Änderungen, übernimmt Codex auch die noch nicht committeten Änderungen in den Worktree. Im Worktree ist kein Branch ausgecheckt. Er hat einen losgelösten HEAD. So kann Codex mehrere Worktrees erstellen, ohne dafür zusätzliche Branches anzulegen.
Ignorierte lokale Dateien in verwaltete Worktrees kopieren
Lokale, von Codex verwaltete Worktrees basieren auf einem Git-Checkout. Dateien, die Git bereits verfolgt, sind daher schon vorhanden. Wenn dein Repository lokale Setup-Dateien ignoriert, die ein neuer Worktree benötigt, lege im Stammverzeichnis des Repositorys eine .worktreeinclude-Datei an. Gib darin die ignorierten Pfade oder Muster im Stil von .gitignore an, die bestimmen, welche Dateien Codex beim Erstellen eines verwalteten Worktrees kopiert.
Verwende diese Möglichkeit für Dateien, die Git bewusst ignoriert, etwa .env, .env.local oder config/secrets.json. Codex kopiert nur ignorierte Dateien, die den Angaben in .worktreeinclude entsprechen. Andere lokale Dateien, die Git nicht verfolgt, kopiert Codex nicht. Liste keine Dateien auf, die Git bereits verfolgt.
Eine von Git ignorierte AGENTS.override.md kopiert Codex automatisch in lokale, von Codex verwaltete Worktrees. Du musst sie daher nicht in .worktreeinclude aufführen.
# .worktreeinclude
.env
.env.local
config/secrets.json
Codex überspringt symbolische Links im Quellverzeichnis und überschreibt keine Dateien, die im neuen Checkout bereits vorhanden sind. Dieses Verhalten gilt nur für lokale Worktrees, die die ChatGPT-Desktop-App verwaltet. Remote-Worktrees und Git-Worktrees, die du selbst über die Befehlszeile erstellst, sind davon ausgenommen.
Einschränkungen bei Branches
Angenommen, Codex hat eine Aufgabe in einem Worktree abgeschlossen und du erstellst dort den Branch feature/a über Branch hier erstellen. Jetzt möchtest du ihn in deinem lokalen Checkout ausprobieren. Beim Versuch, den Branch dort auszuchecken, würdest du folgende Fehlermeldung erhalten:
fatal: 'feature/a' is already used by worktree at '<WORKTREE_PATH>'
Um das Problem zu beheben, müsstest du im Worktree einen anderen Branch als feature/a auschecken.
Wenn du den Branch lokal auschecken möchtest, übergib den Chat an „Lokal“, statt zu versuchen, denselben Branch an beiden Stellen gleichzeitig ausgecheckt zu lassen.
Warum gibt es diese Einschränkung?
Git verhindert, dass derselbe Branch gleichzeitig in mehreren Worktrees ausgecheckt ist. Ein Branch steht für eine einzige veränderliche Referenz (refs/heads/<name>), die den aktuell ausgecheckten Stand eines Arbeitsverzeichnisses bezeichnet.
Wenn ein Branch ausgecheckt ist, ordnet Git dessen HEAD diesem Worktree zu. Git erwartet, dass Operationen wie git commit, git reset, git rebase und git merge die Referenz nacheinander in einer eindeutig festgelegten Reihenfolge aktualisieren. Könnten mehrere Worktrees denselben Branch gleichzeitig auschecken, wäre unklar, welcher Worktree die Branch-Referenz aktualisiert. Bei gleichzeitigen Änderungen könnten Race Conditions auftreten. Dadurch könnten Commits verloren gehen, die Indizes inkonsistent werden oder Unklarheiten bei der Konfliktlösung entstehen.
Da ein Branch immer nur in einem Worktree ausgecheckt sein kann, gibt es für jeden ausgecheckten Branch genau eine maßgebliche Arbeitskopie. Andere Worktrees können mit einem losgelösten HEAD oder auf separaten Branches weiterhin sicher auf dieselben Commits verweisen.
Worktrees aufräumen
Worktrees können viel Speicherplatz belegen. Jeder Worktree hat eigene Repository-Dateien, Abhängigkeiten, Build-Caches und weitere Daten. Deshalb versucht die ChatGPT-Desktop-App, die Anzahl der Worktrees zu begrenzen.
Standardmäßig behält Codex die 15 neuesten von Codex verwalteten Worktrees. Wenn du die Speicherbelegung selbst verwalten möchtest, kannst du das Limit in den Einstellungen ändern oder das automatische Löschen deaktivieren.
Codex versucht, weiterhin benötigte Worktrees zu erhalten. Einen von Codex verwalteten Worktree löscht Codex nicht automatisch, wenn mindestens eine der folgenden Bedingungen zutrifft:
- Ein angehefteter Chat ist mit dem Worktree verknüpft.
- Der Chat läuft noch.
Dauerhafte Worktrees, die in früheren Versionen erstellt wurden, bleiben verfügbar und sind vor der automatischen Bereinigung geschützt. Über das Projektmenü kannst du keine neuen dauerhaften Worktrees mehr erstellen.
Codex löscht verwaltete Worktrees in folgenden Fällen automatisch:
- Du archivierst den zugehörigen Chat.
- Codex muss ältere Worktrees löschen, um das von dir festgelegte Limit einzuhalten.
Bevor Codex einen verwalteten Worktree löscht, speichert Codex den Arbeitsstand als Snapshot. Öffnest du einen Chat, nachdem sein Worktree gelöscht wurde, kannst du den Worktree wiederherstellen.
Häufig gestellte Fragen
Kann ich festlegen, wo Worktrees erstellt werden?
Ja. Standardmäßig erstellt Codex verwaltete Worktrees unter $CODEX_HOME/worktrees. Um einen anderen Speicherort auszuwählen, öffne Einstellungen > Worktrees und ändere das Worktree-Stammverzeichnis.
Kann ich einen Chat zwischen „Lokal“ und „Worktree“ verschieben?
Ja. Über Übergeben im Chatkopf kannst du einen Chat zwischen deinem lokalen Checkout und einem Worktree verschieben. Codex übernimmt die Git-Operationen, die nötig sind, um den Chat sicher von einer Umgebung in die andere zu verschieben. Wenn du den Chat später wieder an einen Worktree übergibst, bringt Codex ihn in den ursprünglich zugeordneten Worktree zurück.
Was passiert mit Chats, wenn ein Worktree gelöscht wird?
Chats können in deinem Verlauf erhalten bleiben, auch wenn das zugehörige Worktree-Verzeichnis gelöscht wurde. Bei verwalteten Worktrees speichert Codex vor dem Löschen einen Snapshot. Wenn du den zugehörigen Chat erneut öffnest, bietet Codex dir an, den Worktree wiederherzustellen.