Ein Git-Worktree ist ein zusätzliches Arbeitsverzeichnis, das an ein bestehendes Git-Repository angehängt wird. Es besitzt einen eigenen ausgecheckten Branch, einen eigenen Index und eigene nicht getrackte Dateien, teilt sich jedoch den Objektspeicher, die Referenzen und die Konfiguration mit dem Haupt-Checkout. Für parallel arbeitende Coding-Agenten ist dies die ideale Isolationseinheit: Jeder Agent erhält ein Verzeichnis, in das kein anderer Prozess schreibt; seine Commits landen auf einem Branch, den niemand sonst ausgecheckt hat; und das Erstellen des Verzeichnisses ist ein einfacher Checkout statt eines zeitraubenden Clones oder Container-Starts. Dieser Artikel erläutert die Funktionsweise, warum Worktrees geteilten Arbeitsverzeichnissen überlegen sind, welche Fehlermodi auftreten können und wie Ivy Tendril automatisch einen Worktree pro Plan erstellt und nach dem Merge wieder aufräumt.
Was ein Worktree ist
Jedes Git-Repository besitzt standardmäßig ein Arbeitsverzeichnis. git worktree add hängt weitere Verzeichnisse an. Jedes davon ist ein vollständiger Checkout, in den Sie per cd wechseln, Dateien bearbeiten, Builds anstoßen und Commits erstellen können.
# Worktree ein Verzeichnis höher auf einem neuen Branch anlegen
git worktree add ../feature-x -b feature-x
# Alle Worktrees dieses Repositorys auflisten
git worktree list
# /Users/dev/app a1b2c3d [main]
# /Users/dev/feature-x a1b2c3d [feature-x]
Das neue Verzeichnis enthält eine .git-Datei, keinen .git-Ordner. Diese Datei verweist zurück auf .git/worktrees/feature-x im Haupt-Repository, wo Index und HEAD für diesen Worktree verwaltet werden. Objekte, Referenzen, Git-Hooks und Konfigurationen werden aus dem Haupt-Repository gelesen. Ein in ../feature-x erstellter Commit ist im Hauptverzeichnis sofort via git log feature-x sichtbar – ganz ohne Push oder Fetch.
Aus diesem Design folgen zwei wichtige Regeln: Ein Branch kann immer nur in genau einem Worktree gleichzeitig ausgecheckt sein. Und das Worktree-Verzeichnis sollte außerhalb des Haupt-Arbeitsverzeichnisses liegen, damit es nicht als ungetrackte Datei im Root-Checkout erscheint.
Warum Worktrees geteilte Verzeichnisse schlagen
Ein Coding-Agent liest und schreibt Dateien, führt Befehle aus und committet. Wenn zwei Agenten dies im selben Verzeichnis tun, entsteht ein unentwirrbares Misch-Diff, und kein Test läuft isoliert gegen die Änderungen eines einzelnen Agenten. Die Alternativen sind ein separater Klon pro Agent, ein Docker-Container pro Agent oder ein Worktree pro Agent.
| Ansatz | Eigener Dateibaum & Branch | Geteilter Objektspeicher | Startaufwand | Laufzeit-Isolation |
|---|---|---|---|---|
| Geteiltes Arbeitsverzeichnis | Nein | Ja | Keiner | Keine |
| Separater Klon pro Agent | Ja | Nein (vollständige Kopie) | Kompletter Klon + Paketinstallation | Keine |
| Docker-Container pro Agent | Ja | Nein (außer gemountet) | Image-Pull + Container-Start | Ja |
| Worktree pro Agent | Ja | Ja | Sofortiger Checkout | Keine |
Ein Worktree bietet einem Agenten genau das, was für funktionale Korrektheit nötig ist (einen privaten Dateibaum und einen privaten Branch), ohne den Overhead einer Container-Virtualisierung. Da der Objektspeicher geteilt wird, kostet ein Repository mit jahrelanger Historie nur einen schnellen Checkout des aktuellen Trees. Paketmanager-Caches (pnpm, Cargo, NuGet), die auf Lockfile-Hashes basieren, verbleiben im Benutzerverzeichnis und werden ohnehin geteilt.
Docker-Container bleiben dort die richtige Wahl, wo Agenten systemweite Bibliotheken installieren oder Netzwerkports binden müssen. Beide Ansätze lassen sich kombinieren: Ein Worktree kann nahtlos in einen Container gemountet werden. Für den Standardablauf (Editieren, Testen, Linting, Committen) reicht der reine Worktree vollkommen aus.
Lesen Sie auch Muster für die Agenten-Orchestrierung, um zu verstehen, wie Isolation in die Gesamtarchitektur eingebettet wird.
Typische Fehlerquellen und wie man sie vermeidet
Worktrees lösen Verzeichniskollisionen. Sie lösen jedoch nicht von allein drei weitere Herausforderungen, die klare Regeln erfordern.
1. Zwei Agenten bearbeiten dieselben Dateien auf verschiedenen Branches
Worktrees isolieren Verzeichnisse, nicht die fachliche Absicht. Wenn zwei Pläne dieselbe Datei auth/session.ts modifizieren, lassen sich beide Branches isoliert sauber committen, führen beim späteren Merge aber unweigerlich zu Konflikten. Die Lösung liegt in der Planungsphase: Erkennen Sie vorab, welche Module berührt werden, und staffeln Sie die Pläne zeitlich oder schneiden Sie die Aufgaben so zu, dass jedes Modul genau einem Plan zugeordnet ist.
2. Nicht committete Änderungen (Dirty Trees)
Bricht ein Agent unerwartet ab oder generiert ein Testlauf temporäre Dateien, bleibt ein Worktree mit uncommitteten Änderungen zurück. git worktree remove verweigert standardmäßig das Löschen eines veränderten Worktrees. Die saubere Strategie eines Orchestrators besteht darin, alle vom Agenten produzierten Änderungen auf dessen Branch zu sichern, damit nichts verloren geht und der Reviewer vollen Einblick behält, bevor der Worktree entfernt wird.
# Status vor dem Entfernen prüfen
git -C ../feature-x status --short
# Sauberen Worktree entfernen
git worktree remove ../feature-x
# Entfernung erzwingen
git worktree remove --force ../feature-x
3. Verwaiste Worktrees
Manuell erstellte Worktrees neigen dazu, vergessen zu werden. Jeder blockiert einen Branch für andere Checkouts und belegt Festplattenplatz. Wird ein Worktree mit rm -rf statt mit git worktree remove gelöscht, behält Git verwaiste Einträge in .git/worktrees/ zurück.
# Prüfen, was bereinigt werden kann
git worktree prune --dry-run --verbose
# Veraltete Einträge entfernen
git worktree prune
Die goldene Regel lautet: Die Instanz, die einen Worktree erzeugt, muss ihn auch wieder zuverlässig entfernen – gebunden an einen fest definierten Status im Lebenszyklus der Aufgabe.
Wie Ivy Tendril Worktrees nutzt
Ivy Tendril ist eine Local-First-Desktop-App (macOS, Windows, Linux), die Coding-Agenten vom Plan bis zum geprüften Pull Request steuert. Worktrees bilden die primäre Ausführungseinheit. Siehe Produktübersicht und Lebenszyklus-Dokumentation.
- Ein Worktree pro Plan: Sobald ein Plan freigegeben wird, erstellt Tendril automatisch einen dedizierten Worktree und Branch. Viele Pläne laufen gleichzeitig, während der Main-Branch sauber bleibt.
- Verifikation im Worktree: Tests, Linter und Diff-Berechnungen laufen isoliert im Worktree des jeweiligen Plans. Die Review-Oberfläche stellt Diff und Testergebnisse nebeneinander dar.
- Automatische Bereinigung: Wird der Pull Request gemergt, löscht Tendril den Worktree automatisch.
- Vollkommen agentenunabhängig: Der im Worktree agierende Agent kann Claude Code, OpenAI Codex CLI, GitHub Copilot CLI, Gemini CLI oder OpenCode sein.
- Vollständig lokal: Worktree, Code, Pläne und Logs verbleiben auf Ihrem Rechner. Siehe Local-First AI Development.
Erste Schritte mit Ivy Tendril
Erleben Sie nahtlose, parallele Agenten-Ausführung ohne Verzeichnis-Chaos:
- Code erkunden: Untersuchen Sie Ivy Tendril auf GitHub (Open Source).
- Dokumentation lesen: Durchsuchen Sie die technischen Anleitungen unter tendril.ivy.app.
- Mit einem Entwickler sprechen: Kontaktieren Sie renco@ivy.app, um eine 30-minütige Architektursitzung zu vereinbaren.