Worktrees

Mit Worktrees kann Codex mehrere unabhängige Unterhaltungen im selben Projekt ausführen, ohne dass sie sich gegenseitig beeinträchtigen. Das Repository, der Worktree und die Befehle verbleiben auf dem Computer oder in der Remote-Entwicklungsumgebung, in der sich das Projekt befindet. Sie können direkt in der ChatGPT-Desktop-App arbeiten oder in der mobilen ChatGPT-App Remote verwenden, um Worktree-Unterhaltungen auf einem verbundenen Computer zu starten, zu steuern, zu genehmigen und zu überprüfen.

Bei Git-Repositorys können geplante Aufgaben in dedizierten Hintergrund-Worktrees ausgeführt werden, damit sie nicht mit Ihrer laufenden Arbeit in Konflikt geraten. In Projekten ohne Versionskontrolle werden geplante Aufgaben direkt im Projektverzeichnis ausgeführt. Sie können Unterhaltungen auch manuell in einem Worktree starten und Handoff verwenden, um eine Unterhaltung zwischen Local und Worktree zu verschieben.

Was ist ein Worktree?

Worktrees funktionieren nur in Projekten, die Teil eines Git-Repositorys sind, da sie im Hintergrund Git-Worktrees verwenden. Mit einem Worktree können Sie eine zweite Kopie („Checkout“) Ihres Repositorys erstellen. Jeder Worktree enthält eine eigene Kopie jeder Datei in Ihrem Repository, doch alle verwenden dieselben Metadaten (Ordner .git) zu Commits, Branches usw. Dadurch können Sie mehrere Branches parallel auschecken und bearbeiten.

Terminologie

• Lokaler Checkout: Das von Ihnen erstellte Repository. In der ChatGPT-Desktop-App manchmal einfach als Local bezeichnet.
• Worktree: Ein Git-Worktree, der in der ChatGPT-Desktop-App aus Ihrem lokalen Checkout erstellt wurde.
• Handoff: Der Ablauf, mit dem ein Chat zwischen Local und Worktree verschoben wird. Codex führt die erforderlichen Git-Operationen aus, um Ihre Arbeit sicher zwischen beiden zu verschieben.

Warum einen Worktree verwenden?

1. Arbeiten Sie parallel mit Codex, ohne Ihre aktuelle Local-Umgebung zu beeinträchtigen.
2. Stellen Sie Hintergrundarbeiten in eine Warteschlange, während Sie sich auf die Arbeit im Vordergrund konzentrieren.
3. Verschieben Sie einen Chat später nach Local, wenn Sie die Arbeit genauer prüfen, testen oder direkter daran mitarbeiten möchten.

Erste Schritte

Worktrees setzen ein Git-Repository voraus. Stellen Sie sicher, dass sich das ausgewählte Projekt in einem solchen Repository befindet.

1. „Worktree“ auswählen

   Wählen Sie in der Ansicht für einen neuen Chat unter dem Eingabefeld Worktree aus. Optional können Sie eine lokale Umgebung auswählen, um Setup-Skripte für den Worktree auszuführen.

2. Ausgangs-Branch auswählen

   Wählen Sie unterhalb des Eingabefelds den Git-Branch aus, auf dem der Worktree basieren soll. Dies kann Ihr Branch main / master, ein Feature-Branch oder Ihr aktueller Branch mit nicht zum Staging hinzugefügten lokalen Änderungen sein.

3. Prompt absenden

   Senden Sie Ihren Prompt ab. Codex erstellt daraufhin einen Git-Worktree auf Grundlage des ausgewählten Branches. Standardmäßig arbeitet Codex mit einem „detached HEAD“.

4. Ort für die weitere Arbeit auswählen

   Wenn Sie so weit sind, können Sie entweder direkt im Worktree weiterarbeiten oder den Chat per Handoff an Ihren lokalen Checkout übergeben. Ein Handoff zu oder von Local verschiebt sowohl Ihren Chat als auch den Code, sodass Sie im jeweils anderen Checkout fortfahren können.

Zwischen Local und Worktree arbeiten

Worktrees sehen Ihrem lokalen Checkout sehr ähnlich und verhalten sich auch so. Der Unterschied besteht darin, welche Rolle sie in Ihrem Arbeitsablauf einnehmen. Sie können sich Local als Vordergrund und Worktree als Hintergrund vorstellen. Mit Handoff können Sie einen Chat zwischen beiden verschieben.

Im Hintergrund führt Handoff die erforderlichen Git-Operationen aus, um Arbeit sicher zwischen zwei Checkouts zu verschieben. Das ist wichtig, weil Git das Auschecken eines Branches jeweils nur an einem Ort zulässt. Wenn Sie einen Branch in einem Worktree auschecken, können Sie ihn nicht gleichzeitig in Ihrem lokalen Checkout auschecken und umgekehrt.

In der Praxis gibt es zwei übliche Vorgehensweisen:

1. Ausschließlich im Worktree arbeiten. Dieser Weg eignet sich am besten, wenn Sie Änderungen direkt im Worktree überprüfen können, etwa weil Sie Abhängigkeiten und Tools mithilfe eines Setup-Skripts für die lokale Umgebung installiert haben.
2. Den Chat per Handoff an Local übergeben. Nutzen Sie diese Möglichkeit, wenn Sie den Chat in den Vordergrund holen möchten, beispielsweise um Änderungen in Ihrer gewohnten IDE zu prüfen oder weil Sie nur eine Instanz Ihrer App ausführen können.

Option 1: Im Worktree arbeiten

Wenn Sie mit Ihren Änderungen ausschließlich im Worktree bleiben möchten, wandeln Sie Ihren Worktree über die Schaltfläche Branch hier erstellen im Chat-Header in einen Branch um.

Anschließend können Sie Ihre Änderungen committen, Ihren Branch in Ihr Remote-Repository pushen und einen Pull Request auf GitHub öffnen.

Sie können Ihre IDE über die Schaltfläche „Open“ in der Kopfzeile für den Worktree öffnen, das integrierte Terminal verwenden oder alles Weitere tun, was Sie im Worktree-Verzeichnis erledigen müssen.

Option 2: Einen Chat per Handoff an Local übergeben

Wenn Sie einen Chat in den Vordergrund holen möchten, wählen Sie im Chat-Header Hand off aus und verschieben Sie ihn nach Local.

Dieser Weg eignet sich gut, wenn Sie die Änderungen in Ihrem gewohnten IDE-Fenster lesen, Ihren vorhandenen Entwicklungsserver ausführen oder die Arbeit in derselben Umgebung validieren möchten, die Sie bereits täglich verwenden.

Codex führt die erforderlichen Git-Schritte aus, um den Chat sicher zwischen dem Worktree und Ihrem lokalen Checkout zu verschieben.

Jeder Chat bleibt dauerhaft demselben Worktree zugeordnet. Wenn Sie den Chat später wieder an einen Worktree übergeben, bringt Codex ihn in dieselbe Hintergrundumgebung zurück, sodass Sie dort fortfahren können, wo Sie aufgehört haben.

Da Handoff Git-Operationen verwendet, werden Dateien, die Bestandteil Ihrer Datei .gitignore sind, nicht zusammen mit dem Chat verschoben, es sei denn, Codex kopiert sie mit .worktreeinclude in einen lokal verwalteten Worktree.

Erweiterte Details

Von Codex verwaltete und permanente Worktrees

Standardmäßig verwenden Chats einen von Codex verwalteten Worktree. Diese sollen leichtgewichtig und kurzlebig sein. Ein von Codex verwalteter Worktree ist in der Regel einem einzelnen Chat vorbehalten. Wenn Sie diesen Chat später dorthin zurückgeben, bringt Codex ihn wieder in denselben Worktree.

Wenn Sie eine langlebige Umgebung benötigen, erstellen Sie über das Dreipunktmenü eines Projekts in der Seitenleiste einen permanenten Worktree. Dadurch wird ein neuer permanenter Worktree als eigenständiges Projekt erstellt. Permanente Worktrees werden nicht automatisch gelöscht und Sie können mehrere Chats aus demselben Worktree starten.

So verwaltet Codex Worktrees für Sie

Codex erstellt Worktrees in $CODEX_HOME/worktrees. Als Ausgangs-Commit dient der HEAD-Commit des Branches, der beim Start Ihres Chats ausgewählt war. Wenn Sie einen Branch mit lokalen Änderungen ausgewählt haben, wendet Codex auch die nicht committeten Änderungen auf den Worktree an. Der Worktree ist nicht als Branch ausgecheckt. Er befindet sich in einem detached HEAD-Zustand. Dadurch kann Codex mehrere Worktrees erstellen, ohne Ihre Branches zu verunreinigen.

Ignorierte lokale Dateien in verwaltete Worktrees kopieren

Lokale, von Codex verwaltete Worktrees basieren auf einem Git-Checkout, sodass nachverfolgte Dateien bereits vorhanden sind. Falls Ihr Repository lokale Setup-Dateien ignoriert, die ein neuer Worktree benötigt, fügen Sie dem Stammverzeichnis des Repositorys eine Datei .worktreeinclude hinzu und führen Sie darin die ignorierten Pfade oder Muster im Stil von .gitignore auf, die Codex beim Erstellen eines verwalteten Worktrees kopieren soll.

Verwenden Sie dies für Dateien, die Git absichtlich ignoriert, beispielsweise .env, .env.local oder config/secrets.json. Codex kopiert nur ignorierte Dateien, die .worktreeinclude entsprechen; andere lokale Dateien, die Git nicht nachverfolgt, werden nicht kopiert. Führen Sie keine nachverfolgten Dateien auf.

Codex kopiert eine ignorierte AGENTS.override.md automatisch in lokal verwaltete Worktrees. Sie müssen sie daher nicht in .worktreeinclude aufführen.

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

Codex überspringt symbolische Quelllinks und überschreibt keine Dateien, die im neuen Checkout bereits vorhanden sind. Dieses Verhalten gilt für lokal verwaltete Worktrees der ChatGPT-Desktop-App, nicht für Remote-Worktrees oder Git-Worktrees, die Sie selbst über die Befehlszeile erstellen.

Einschränkungen für Branches

Angenommen, Codex schließt eine Arbeit in einem Worktree ab und Sie erstellen dort über Branch hier erstellen einen Branch feature/a. Nun möchten Sie ihn in Ihrem lokalen Checkout ausprobieren. Wenn Sie versuchen, den Branch auszuchecken, erhalten Sie den folgenden Fehler:

fatal: 'feature/a' is already used by worktree at '<WORKTREE_PATH>'

Um das Problem zu beheben, müssten Sie im Worktree einen anderen Branch anstelle von feature/a auschecken.

Wenn Sie den Branch lokal auschecken möchten, verschieben Sie den Chat per Handoff nach Local, anstatt zu versuchen, denselben Branch gleichzeitig an beiden Orten ausgecheckt zu lassen.

Worktrees bereinigen

Worktrees können viel Speicherplatz belegen. Jeder Worktree verfügt über einen eigenen Satz von Repository-Dateien, Abhängigkeiten, Build-Caches usw. Daher versucht die ChatGPT-Desktop-App, die Anzahl der Worktrees auf einen angemessenen Wert zu begrenzen.

Standardmäßig behält Codex Ihre 15 zuletzt verwendeten, von Codex verwalteten Worktrees. Sie können diesen Grenzwert ändern oder das automatische Löschen in den Einstellungen deaktivieren, wenn Sie die Speicherplatznutzung lieber selbst verwalten möchten.

Codex versucht, weiterhin wichtige Worktrees nicht zu löschen. Von Codex verwaltete Worktrees werden nicht automatisch gelöscht, wenn:

• ein angehefteter Chat mit dem Worktree verknüpft ist
• der Chat noch läuft
• es sich um einen permanenten Worktree handelt

Von Codex verwaltete Worktrees werden automatisch gelöscht, wenn:

• Sie den zugehörigen Chat archivieren
• Codex ältere Worktrees löschen muss, um Ihren konfigurierten Grenzwert einzuhalten

Bevor Codex einen verwalteten Worktree löscht, speichert es einen Snapshot der darin enthaltenen Arbeit. Wenn Sie einen Chat öffnen, nachdem dessen Worktree gelöscht wurde, wird Ihnen die Option angeboten, ihn wiederherzustellen.

Häufig gestellte Fragen