ChatGPT-Dokumentation
Deutsch
Kontakt goolvyouyou@gmail.com

Worktrees

Verwenden Sie Git-Worktrees in Codex in der ChatGPT-Desktop-App, um Chats parallel auszuführen

In der ChatGPT-Desktop-App ermöglichen Worktrees Codex, mehrere unabhängige Chats im selben Projekt auszuführen, ohne dass sie sich gegenseitig beeinträchtigen. Bei Git-Repositorys können geplante Aufgaben in dedizierten Hintergrund-Worktrees ausgeführt werden, sodass sie nicht mit Ihrer laufenden Arbeit in Konflikt geraten. In Projekten ohne Versionsverwaltung werden geplante Aufgaben direkt im Projektverzeichnis ausgeführt. Sie können Chats auch manuell in einem Worktree starten und mit Handoff einen Chat zwischen Local und Worktree verschieben.

Was ist ein Worktree?

Worktrees funktionieren nur in Projekten, die Teil eines Git-Repositorys sind, da sie intern 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, während alle dieselben Metadaten (Ordner .git) zu Commits, Branches und weiteren Elementen gemeinsam nutzen. So können Sie mehrere Branches parallel auschecken und bearbeiten.

Terminologie

  • Lokaler Checkout: Das von Ihnen erstellte Repository. In der ChatGPT-Desktop-App gelegentlich 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 übernimmt die Git-Vorgänge, die erforderlich sind, um Ihre Arbeit sicher zwischen beiden zu verschieben.

Warum sollten Sie 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 Änderungen 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 Einrichtungsskripte für den Worktree auszuführen.

  2. Ausgangs-Branch auswählen

    Wählen Sie unter dem Eingabefeld 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 vorgemerkten 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 an Ihren lokalen Checkout übergeben. Bei einem Handoff an oder von Local werden sowohl Ihr Chat als auch Ihr Code verschoben, 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.

Intern übernimmt Handoff die Git-Vorgänge, die erforderlich sind, um Arbeit sicher zwischen zwei Checkouts zu verschieben. Dies 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 gängige Vorgehensweisen:

  1. Ausschließlich im Worktree arbeiten. Diese Vorgehensweise eignet sich am besten, wenn Sie Änderungen direkt im Worktree überprüfen können, beispielsweise weil Sie Abhängigkeiten und Werkzeuge mithilfe eines Einrichtungsskripts für die lokale Umgebung installiert haben.
  2. Den Chat an Local übergeben. Verwenden Sie diese Vorgehensweise, wenn Sie den Chat in den Vordergrund holen möchten, beispielsweise weil Sie Änderungen in Ihrer üblichen IDE prüfen möchten oder 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 Create branch here 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.

Über die Schaltfläche „Open“ im Header können Sie Ihre IDE für den Worktree öffnen. Sie können außerdem das integrierte Terminal oder jedes andere Werkzeug verwenden, das Sie im Worktree-Verzeichnis benötigen.

Worktree-Chatansicht mit Branch-Steuerelementen und Worktree-Details (heller Modus)

Beachten Sie: Wenn Sie in einem Worktree einen Branch erstellen, können Sie ihn in keinem anderen Worktree auschecken, auch nicht in Ihrem lokalen Checkout.

Option 2: Einen Chat 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.

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

Codex übernimmt die Git-Schritte, die erforderlich sind, um den Chat sicher zwischen dem Worktree und Ihrem lokalen Checkout zu verschieben.

Jedem Chat bleibt dauerhaft derselbe Worktree zugeordnet. Wenn Sie den Chat später wieder an einen Worktree übergeben, bringt Codex ihn in dieselbe Hintergrundumgebung zurück, sodass Sie Ihre Arbeit an der vorherigen Stelle fortsetzen können.

Handoff-Dialog zum Verschieben eines Chats von einem Worktree nach Local (heller Modus)

Sie können auch in die andere Richtung vorgehen. Wenn Sie bereits in Local arbeiten und den Vordergrund freigeben möchten, verschieben Sie den Chat mit Hand off in einen Worktree. Dies ist nützlich, wenn Codex im Hintergrund weiterarbeiten soll, während Sie sich lokal wieder einer anderen Aufgabe widmen.

Da Handoff Git-Vorgänge verwendet, werden Dateien, die Teil Ihrer Datei .gitignore sind, nicht zusammen mit dem Chat verschoben, sofern Codex sie nicht mit .worktreeinclude in einen lokal verwalteten Worktree kopiert.

Erweiterte Details

Von Codex verwaltete und permanente Worktrees

Standardmäßig verwenden Chats einen von Codex verwalteten Worktree. Diese Worktrees sind als leichtgewichtige, temporäre Umgebungen vorgesehen. Ein von Codex verwalteter Worktree ist üblicherweise einem einzelnen Chat vorbehalten. Wenn Sie diesen Chat später wieder dorthin übergeben, bringt Codex ihn in denselben Worktree zurück.

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. Der Ausgangs-Commit ist der Commit HEAD des Branches, den Sie beim Starten Ihrer Aufgabe auswählen. 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 überladen.

Ignorierte lokale Dateien in verwaltete Worktrees kopieren

Lokal von Codex verwaltete Worktrees beginnen mit einem Git-Checkout, sodass nachverfolgte Dateien bereits vorhanden sind. Wenn Ihr Repository lokale Einrichtungsdateien ignoriert, die ein neuer Worktree benötigt, fügen Sie im Stammverzeichnis des Repositorys eine Datei .worktreeinclude hinzu. Listen 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, etwa .env, .env.local oder config/secrets.json. Codex kopiert nur ignorierte Dateien, die mit .worktreeinclude übereinstimmen. Andere lokale Dateien, die Git nicht nachverfolgt, werden nicht kopiert. Listen Sie keine nachverfolgten Dateien auf.

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

# .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 lokale, von der ChatGPT-Desktop-App verwaltete Worktrees, 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 mit Create branch here einen Branch feature/a. Nun möchten Sie ihn in Ihrem lokalen Checkout ausprobieren. Beim Versuch, den Branch auszuchecken, würden Sie folgende Fehlermeldung erhalten:

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

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

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

Warum gibt es diese Einschränkung?

Git verhindert, dass derselbe Branch gleichzeitig in mehr als einem Worktree ausgecheckt wird, da ein Branch eine einzelne veränderliche Referenz (refs/heads/<name>) darstellt, deren Bedeutung der „aktuell ausgecheckte Zustand“ eines Arbeitsverzeichnisses ist.

Wenn ein Branch ausgecheckt ist, behandelt Git dessen HEAD als Eigentum dieses Worktrees und erwartet, dass Vorgänge wie Commits, Resets, Rebases und Merges diese Referenz auf klar definierte, sequenzielle Weise fortschreiben. Wenn mehrere Worktrees denselben Branch gleichzeitig auschecken könnten, entstünden Mehrdeutigkeiten und Race Conditions hinsichtlich der Frage, welcher Worktree mit seinen Vorgängen die Branch-Referenz aktualisiert. Dies könnte zu verlorenen Commits, inkonsistenten Indizes oder einer unklaren Konfliktauflösung führen.

Durch die Regel, dass jeder Branch jeweils nur einem Worktree zugeordnet sein darf, stellt Git sicher, dass jeder Branch eine einzige maßgebliche Arbeitskopie besitzt. Andere Worktrees können weiterhin über detached HEADs oder separate Branches sicher auf dieselben Commits verweisen.

Worktrees bereinigen

Worktrees können viel Speicherplatz beanspruchen. Jeder Worktree verfügt über einen eigenen Satz von Repository-Dateien, Abhängigkeiten, Build-Caches und weiteren Daten. Daher versucht die ChatGPT-Desktop-App, die Anzahl der Worktrees auf ein angemessenes Maß zu begrenzen.

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

Codex versucht, das Löschen weiterhin wichtiger Worktrees zu vermeiden. 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 den von Ihnen 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 eine Option zum Wiederherstellen angezeigt.

Häufig gestellte Fragen

Kann ich festlegen, wo Worktrees erstellt werden?

Ja. Codex erstellt verwaltete Worktrees standardmäßig unter $CODEX_HOME/worktrees. Um einen anderen Speicherort auszuwählen, öffnen Sie Settings > Worktrees und ändern Sie Worktree root.

Kann ich einen Chat zwischen Local und Worktree verschieben?

Ja. Verwenden Sie Hand off im Chat-Header, um einen Chat zwischen Ihrem lokalen Checkout und einem Worktree zu verschieben. Codex führt die erforderlichen Git-Vorgänge aus, um den Chat sicher zwischen Umgebungen zu verschieben. Wenn Sie einen Chat später wieder an einen Worktree übergeben, bringt Codex ihn in denselben zugehörigen Worktree zurück.

Was geschieht mit Chats, wenn ein Worktree gelöscht wird?

Chats können in Ihrem Verlauf verbleiben, selbst wenn das zugrunde liegende Worktree-Verzeichnis gelöscht wurde. Bei von Codex verwalteten Worktrees speichert Codex vor dem Löschen des Worktrees einen Snapshot und bietet dessen Wiederherstellung an, wenn Sie den zugehörigen Chat erneut öffnen. Permanente Worktrees werden nicht automatisch gelöscht, wenn Sie deren Chats archivieren.