# git worktree: Mehrere KI-Agenten am selben Projekt, ohne dass sie sich stören 2026-11-03 · Steven Noack · https://stevennoack.de/artikel/fachartikel-zum-suchbegriff-git-worktree-2900-suchen-monat/ # git worktree: Mehrere KI-Agenten am selben Projekt, ohne dass sie sich stören Ein Worktree ist eine zweite Arbeitskopie desselben Git-Repositorys in einem eigenen Ordner. Jeder Worktree hat einen eigenen ausgecheckten Branch, einen eigenen HEAD und einen eigenen Index. Alles andere teilt er mit dem Repository, vor allem die Commits und die Branches [1]. Ein Commit im einen Ordner ist deshalb sofort im anderen sichtbar, ohne Push und ohne Pull. Wer zwei KI-Agenten gleichzeitig am selben Projekt arbeiten lässt, gibt jedem einen eigenen Worktree. Dann ändert keiner die Dateien, an denen der andere gerade sitzt. Drei Handwerker in einer Küche stehen sich im Weg, drei Handwerker in drei Räumen desselben Hauses nicht. Das Haus ist das Repository, die Räume sind die Worktrees. Die Angaben zu Git stammen aus dem offiziellen Handbuch, zuletzt geändert mit Git 2.56.0 am 28.09.2026 [1], und aus einem eigenen Test mit Git 2.52.0 unter macOS vom 03.11.2026 [6]. Alle Angaben haben den Stand vom 03.11.2026. ## Worktree, Branch oder Klon? Ein Worktree ist ein zusätzlicher Ordner für dasselbe Repository Die drei Begriffe meinen verschiedene Dinge: | | Branch | Worktree | Klon | |---|---|---|---| | Was es ist | ein Name für eine Reihe von Commits | ein weiterer Arbeitsordner, in dem ein Branch ausgecheckt ist | eine vollständige zweite Kopie des Repositorys | | Eigene Dateien auf der Platte | nein, ein Ordner zeigt immer nur einen Branch | ja | ja | | Historie | gemeinsam | gemeinsam mit dem Hauptordner | eigene Kopie, Abgleich über Push und Pull | | Gleichzeitig an zwei Ständen arbeiten | nur nacheinander, per Wechsel | ja | ja | Ein Branch allein reicht nicht für paralleles Arbeiten. Ein Ordner hat genau einen ausgecheckten Stand. Wer den Branch wechselt, tauscht die Dateien in diesem Ordner aus. Ein Klon löst das, kopiert aber die ganze Historie ein zweites Mal und braucht Push und Pull, damit die Kopien voneinander erfahren. Ein Worktree liegt dazwischen: eigene Dateien wie beim Klon, gemeinsame Historie wie beim Branch. Das Handbuch unterscheidet den Hauptordner (main worktree), in dem das Repository ursprünglich liegt, von den verknüpften Worktrees (linked worktrees), die mit `git worktree add` dazukommen [1]. ## Welche Befehle braucht git worktree im Alltag? add, list, remove, prune und lock Für den Alltag reichen fünf Unterbefehle. Sie funktionieren im Hauptordner und in jedem Worktree desselben Repositorys. ### git worktree add legt einen neuen Arbeitsordner an ```bash # neuer Ordner mit neuem Branch git worktree add -b login-formular ../projekt-login # kurz: der Ordnername wird zum Branchnamen git worktree add ../login-formular # vorhandenen Branch in einem neuen Ordner auschecken git worktree add ../projekt-suche feature-suche # ohne Branch, mit losgelöstem HEAD, etwa zum Ausprobieren git worktree add -d ../projekt-test ``` Fehlt die Angabe eines Branches, nimmt Git den Ordnernamen. Gibt es einen Branch dieses Namens, checkt Git ihn aus. Gibt es ihn nicht, legt Git ihn auf Basis des aktuellen HEAD an [1]. Die Beispiele legen die Worktrees neben den Projektordner (`../`), damit sie nicht innerhalb des Hauptordners liegen. ### git worktree list zeigt alle Arbeitsordner ```bash git worktree list ``` Zuerst steht der Hauptordner, danach die verknüpften Worktrees. Zu jedem zeigt Git den Commit und den Branch oder den Vermerk „detached HEAD“. Gesperrte Worktrees sind als „locked“ markiert, solche ohne vorhandenen Ordner als „prunable“ [1]. ### git worktree remove löscht nur saubere Worktrees ```bash git worktree remove ../projekt-login # mit unversionierten oder geänderten Dateien git worktree remove --force ../projekt-login ``` Ohne Zusatz entfernt Git nur einen sauberen Worktree. Sauber heißt laut Handbuch: keine unversionierten Dateien und keine Änderungen an versionierten Dateien. Für alles andere, und für Worktrees mit Submodulen, braucht es `--force`. Ein gesperrter Worktree verlangt `--force` zweimal. Den Hauptordner kann `remove` gar nicht entfernen [1]. Von einem Löschen des Branches spricht das Handbuch bei `remove` nicht. Der Branch und seine Commits liegen im gemeinsamen Repository und bleiben dort, bis sie jemand mit `git branch -d` löscht. ### git worktree prune räumt nach von Hand gelöschten Ordnern auf ```bash git worktree prune ``` Wer einen Worktree-Ordner im Dateimanager oder mit `rm -rf` löscht, lässt Verwaltungsdaten im Repository zurück, unter `$GIT_DIR/worktrees`. `prune` entfernt diese Reste für Ordner, die es nicht mehr gibt. Git erledigt das sonst irgendwann von selbst, gesteuert über die Einstellung `gc.worktreePruneExpire` [1]. Bis dahin meldet `list` solche Einträge als „prunable“. ### git worktree lock schützt Worktrees auf externen Laufwerken ```bash git worktree lock --reason "liegt auf der externen SSD" ../projekt-archiv git worktree unlock ../projekt-archiv ``` Ein gesperrter Worktree wird nicht beschnitten, nicht verschoben und nicht gelöscht. Das ist gedacht für Ordner auf Laufwerken, die nicht immer angeschlossen sind. Ohne Sperre könnte `prune` einen solchen Worktree für verschwunden halten [1]. Zwei weitere Befehle braucht man seltener: `git worktree move` verschiebt einen Worktree, `git worktree repair` stellt die Verknüpfung wieder her, wenn ein Ordner ohne Git umgezogen ist [1]. ## Warum brauchen KI-Agenten Worktrees? Zwei Agenten in einem Ordner überschreiben sich Ein Ordner hat einen HEAD, einen Index und einen Satz Dateien. Arbeiten zwei Agenten darin, teilen sie alle drei. Das führt zum Beispiel zu diesen Störungen: 1. Ein Agent wechselt den Branch. Damit tauscht er die Dateien aus, die der andere gerade bearbeitet. 2. Beide ändern dieselbe Datei. Wer zuletzt speichert, überschreibt die Änderung des anderen. 3. Ein Agent nimmt mit `git add -A` alle Änderungen in seinen Commit. Darin landet auch die halbfertige Arbeit des anderen. Mit je einem Worktree hat jeder Agent eigene Dateien, einen eigenen Index und einen eigenen Branch. Das Zusammenführen passiert erst, wenn eine Aufgabe fertig ist, über einen gewöhnlichen Merge: ```bash git worktree add -b agent-a ../projekt-agent-a git worktree add -b agent-b ../projekt-agent-b # Agent A startet in ../projekt-agent-a, Agent B in ../projekt-agent-b # später, im Hauptordner git merge agent-a git merge agent-b git worktree remove ../projekt-agent-a git branch -d agent-a ``` Worktrees verhindern keine Merge-Konflikte. Ändern beide Agenten dieselben Zeilen, meldet Git beim Merge einen Konflikt, genau wie bei zwei Menschen. Was außerhalb des Ordners liegt, teilen die Agenten weiterhin: eine lokale Datenbank, einen Port für den Entwicklungsserver, Ordner, die per Verknüpfung in mehrere Worktrees eingebunden sind. Aufgaben schneidet man deshalb so zu, dass jede einen eigenen Bereich des Projekts betrifft. ## Welche Fallen hat git worktree? Blockiertes Löschen, mitgelöschte Ordner, doppelte Branches, fehlende .env ### Eine einzige unversionierte Datei blockiert remove, auch eine .DS_Store Im Test reichte eine einzige neue, unversionierte Datei, und `git worktree remove` brach mit Exit-Code 128 ab. Die Meldung der deutschen Git-Fassung lautete: „enthält geänderte oder nicht versionierte Dateien, benutzen Sie --force zum Löschen“ [6]. Unter macOS trifft das oft eine Datei, die niemand bewusst angelegt hat: `.DS_Store`. macOS legt sie selbst in Ordnern an. Steht sie nicht in der `.gitignore`, gilt sie für Git als unversioniert und blockiert das Entfernen. In einem Fall vom 21.10.2026 ließ sich ein Worktree deshalb erst mit `--force` löschen [7]. Vor dem Löschen zeigt `git status` im Worktree, welche Datei blockiert. Ist es nur `.DS_Store`, ist `--force` harmlos. Dauerhaft hilft ein Eintrag `.DS_Store` in der `.gitignore` des Projekts oder in der globalen Ignorierliste von Git. Ignorierte Dateien blockieren `remove` nicht, wie der nächste Abschnitt zeigt. ### git worktree remove löscht ignorierte Ordner wie node_modules ohne Rückfrage Was in der `.gitignore` steht, behandelt `remove` anders. Im Test enthielt ein Worktree nur einen ignorierten Ordner `node_modules/`. `git worktree remove` entfernte den Worktree ohne `--force` und löschte den ignorierten Ordner gleich mit [6]. Das Handbuch sagt zu ignorierten Dateien nichts ausdrücklich [1]. Geprüft ist das Verhalten nur mit Git 2.52.0. Für `node_modules` ist das meist gewollt. Gefährlich wird es bei ignorierten Dateien, die sich nicht neu erzeugen lassen, etwa eine `.env` mit Zugangsdaten oder eine lokale Datenbankdatei. Solche Dateien gehören vor dem `remove` aus dem Worktree heraus, denn Git fragt nicht nach. ### Ein Branch lässt sich nur in einem Worktree gleichzeitig auschecken `git worktree add` verweigert einen Branch, der schon in einem anderen Worktree ausgecheckt ist [1]. Im Test lautete die Meldung „'f2' wird bereits von Arbeitsverzeichnis in '/private/tmp/wtt/w2' verwendet“, Exit-Code 128 [6]. Mit `--force` lässt sich die Sperre umgehen [1]. Dann teilen sich zwei Ordner wieder einen Branch, was Worktrees gerade vermeiden sollen. Für zwei Agenten heißt das: zwei Branches anlegen, auch wenn beide vom selben Stand ausgehen. Dasselbe gilt für den Hauptbranch. Ist `main` im Hauptordner ausgecheckt, kann kein Worktree `main` auschecken. Wer einen Worktree auf dem Stand von `main` braucht, legt einen neuen Branch davon an oder nimmt `-d` für einen losgelösten HEAD. ### Die .env-Datei fehlt im neuen Worktree Ein neuer Worktree enthält nur, was versioniert ist. Ignorierte Dateien fehlen [5]. Das betrifft vor allem `.env` und `node_modules`. Ein Agent, der im neuen Ordner die Tests startet, scheitert dann an fehlenden Zugangsdaten oder Paketen, obwohl im Hauptordner alles läuft. Mit reinem Git bleibt nur, solche Dateien nach dem `add` von Hand zu kopieren oder neu zu installieren. Orca nimmt diesen Schritt ab, wie der nächste Abschnitt zeigt. ## Wie arbeitet man mit Worktrees ohne Kommandozeile? Orca legt je Aufgabe einen Worktree mit eigenem Branch an Orca ist ein quelloffenes Programm unter MIT-Lizenz, das mit Worktrees als Grundeinheit arbeitet [2][3]. Es läuft auf macOS (Apple Silicon und Intel), Windows und Linux. Für Linux gibt es AppImage, deb, rpm und AUR, jeweils für x64 und arm64. Dazu kommen eine Begleit-App fürs Telefon und eine Laufzeit für entfernte Rechner [2][3][4]. Aktuell ist Version 1.4.247 vom 03.11.2026 [4]. Das Repository verweist auf orca.dev, das auf onorca.dev weiterleitet; dort liegt die Dokumentation [2][5]. So geht Orca mit Worktrees um, laut Dokumentation [5]: - Jede Aufgabe bekommt per `git worktree` eine eigene Kopie auf der Platte, mit eigenem Branch und eigenen Terminals für die Agenten. - Jedes Repository hat einen Basis-Stand, meist `origin/main`. Für jeden Worktree lässt sich ein anderer Start wählen: die Basis, ein anderer lokaler Branch, ein Commit oder ein entfernter Branch. - Das Anlegen läuft im Hintergrund. `git fetch` und `git worktree add` arbeiten weiter, während der Dialog schon geschlossen ist. - Den Branchnamen leitet Orca aus dem Namen des Arbeitsbereichs ab oder aus einem verknüpften Pull Request oder Ticket bei GitHub, Linear, Jira oder GitLab. Bei Linear übernimmt es den dort vorgeschlagenen Branchnamen. - Von Hand mit `git worktree add` angelegte Worktrees gelten als „extern“, bis man sie in Orca einblendet. Per Skript legt `orca worktree create` einen Worktree an. ### Orca löst das Problem fehlender ignorierter Dateien auf drei Wegen Auch bei Orca ist ein neuer Worktree ein sauberer Checkout ohne ignorierte Dateien. Drei Einstellungen holen sie herein [5]: 1. „Worktree Shared Paths“ in den Einstellungen. Auf macOS legt Orca dafür einen APFS-Klon an, auf anderen Systemen eine symbolische Verknüpfung. 2. `worktree.sharedDirectories` in der Datei `orca.yaml`. Die genannten Ordner, etwa `node_modules`, werden zwischen den Worktrees geteilt. 3. Die Datei `.worktreeinclude`. Die dort genannten Dateien, etwa `.env`, werden in jeden neuen Worktree kopiert. Eine kopierte `.env` kann jeder Worktree für sich ändern. Ein geteilter Ordner ist dagegen für alle derselbe. Installiert ein Agent darin Pakete, sehen alle anderen das Ergebnis. ### Löschen in Orca entfernt Ordner und Branch Anders als `git worktree remove` löscht Orca beim Entfernen eines Worktrees Ordner und Branch, nach einer Rückfrage. Scheitert der Git-Befehl dabei, bietet Orca „Force Delete“ an. Beim Löschen mehrerer Worktrees auf einmal behält Orca Branches, die noch Commits enthalten, die nicht gemergt sind [5]. In welchem Ordner Orca die Worktrees standardmäßig ablegt, steht weder in der Worktree-Dokumentation noch im README [3][5]. ## Häufige Fragen zu git worktree ### Was ist besser, Worktree oder Branch? Beides zusammen. Ein Worktree braucht einen Branch, oder einen losgelösten HEAD. Ein Branch allein erlaubt nur, nacheinander an verschiedenen Ständen zu arbeiten. Der Worktree gibt dem Branch einen eigenen Ordner, sodass mehrere Stände gleichzeitig offen sind [1]. ### Kann man einen Worktree löschen, ohne Arbeit zu verlieren? Ja, wenn alles committet ist. Commits liegen im gemeinsamen Repository, nicht im Ordner, und `git worktree remove` löscht den Branch nicht [1]. Verloren gehen nicht committete Änderungen und unversionierte Dateien, sobald `--force` im Spiel ist. Ignorierte Dateien wie `.env` oder `node_modules` löschte `remove` im Test sogar ohne `--force` mit [6]. Orca löscht zusätzlich den Branch, behält beim Sammellöschen aber Branches mit nicht gemergten Commits [5]. ### Kann derselbe Branch in zwei Worktrees ausgecheckt sein? Nein, nicht ohne `--force`. Git lehnt einen Branch ab, der bereits in einem anderen Worktree ausgecheckt ist [1][6]. ### Was passiert, wenn man einen Worktree-Ordner einfach löscht? Der Ordner ist weg, im Repository bleiben Verwaltungsdaten zurück. `git worktree list` zeigt den Eintrag als „prunable“, `git worktree prune` räumt ihn auf [1]. Der Branch bleibt erhalten. ### Brauchen zwei KI-Agenten im selben Repository zwei Branches? Ja. Ein Branch lässt sich nur in einem Worktree auschecken [1]. Jeder Agent bekommt deshalb einen eigenen Worktree mit eigenem Branch. Fertige Arbeit kommt über einen Merge zurück in den Hauptbranch. ## Quellen zu git worktree und Orca, abgerufen am 03.11.2026 1. Git-Handbuch: git-worktree, zuletzt geändert in Git 2.56.0 (28.09.2026). https://git-scm.com/docs/git-worktree 2. GitHub-API: Repository stablyai/orca (Lizenz, Homepage). https://api.github.com/repos/stablyai/orca 3. GitHub: stablyai/orca, README. https://github.com/stablyai/orca/blob/main/README.md 4. GitHub: stablyai/orca, aktuelle Veröffentlichung v1.4.247 (03.11.2026). https://github.com/stablyai/orca/releases/latest 5. Orca-Dokumentation: Worktrees. https://www.onorca.dev/docs/model/worktrees 6. Eigener Test vom 03.11.2026 mit Git 2.52.0 unter macOS (unversionierte Datei bei `remove`, ignorierter Ordner `node_modules/`, derselbe Branch in zwei Worktrees). Nicht veröffentlicht. 7. Eigene Beobachtung vom 21.10.2026 unter macOS: `.DS_Store` blockiert `git worktree remove`. Nicht veröffentlicht.