{
    "kind": 30023,
    "id": "5d791d660cc97624f7d323681f49cacc791bef66c58cf64979edd49b1eda1c8b",
    "pubkey": "c1baf4f74cd829963828b1da8d73e52cc94caa6d8dc944f7ca450a75c4b3311f",
    "created_at": 1793731154,
    "tags": [
        [
            "title",
            "git worktree: Mehrere KI-Agenten am selben Projekt, ohne dass sie sich st\u00f6ren"
        ],
        [
            "d",
            "fachartikel-zum-suchbegriff-git-worktree-2900-suchen-monat"
        ],
        [
            "summary",
            "git worktree erkl\u00e4rt: Unterschied zu Branch und Klon, die Befehle add, list, remove, prune und lock, Fallen wie .DS_Store und node_modules, parallele KI-Agenten und Orca. Stand 03.11.2026."
        ],
        [
            "published_at",
            "1793731153"
        ]
    ],
    "content": "# git worktree: Mehrere KI-Agenten am selben Projekt, ohne dass sie sich st\u00f6ren\n\nEin 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\u00e4sst, gibt jedem einen eigenen Worktree. Dann \u00e4ndert keiner die Dateien, an denen der andere gerade sitzt.\n\nDrei Handwerker in einer K\u00fcche stehen sich im Weg, drei Handwerker in drei R\u00e4umen desselben Hauses nicht. Das Haus ist das Repository, die R\u00e4ume sind die Worktrees.\n\nDie Angaben zu Git stammen aus dem offiziellen Handbuch, zuletzt ge\u00e4ndert 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.\n\n## Worktree, Branch oder Klon? Ein Worktree ist ein zus\u00e4tzlicher Ordner f\u00fcr dasselbe Repository\n\nDie drei Begriffe meinen verschiedene Dinge:\n\n| | Branch | Worktree | Klon |\n|---|---|---|---|\n| Was es ist | ein Name f\u00fcr eine Reihe von Commits | ein weiterer Arbeitsordner, in dem ein Branch ausgecheckt ist | eine vollst\u00e4ndige zweite Kopie des Repositorys |\n| Eigene Dateien auf der Platte | nein, ein Ordner zeigt immer nur einen Branch | ja | ja |\n| Historie | gemeinsam | gemeinsam mit dem Hauptordner | eigene Kopie, Abgleich \u00fcber Push und Pull |\n| Gleichzeitig an zwei St\u00e4nden arbeiten | nur nacheinander, per Wechsel | ja | ja |\n\nEin Branch allein reicht nicht f\u00fcr paralleles Arbeiten. Ein Ordner hat genau einen ausgecheckten Stand. Wer den Branch wechselt, tauscht die Dateien in diesem Ordner aus. Ein Klon l\u00f6st 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.\n\nDas Handbuch unterscheidet den Hauptordner (main worktree), in dem das Repository urspr\u00fcnglich liegt, von den verkn\u00fcpften Worktrees (linked worktrees), die mit `git worktree add` dazukommen [1].\n\n## Welche Befehle braucht git worktree im Alltag? add, list, remove, prune und lock\n\nF\u00fcr den Alltag reichen f\u00fcnf Unterbefehle. Sie funktionieren im Hauptordner und in jedem Worktree desselben Repositorys.\n\n### git worktree add legt einen neuen Arbeitsordner an\n\n```bash\n# neuer Ordner mit neuem Branch\ngit worktree add -b login-formular ../projekt-login\n\n# kurz: der Ordnername wird zum Branchnamen\ngit worktree add ../login-formular\n\n# vorhandenen Branch in einem neuen Ordner auschecken\ngit worktree add ../projekt-suche feature-suche\n\n# ohne Branch, mit losgel\u00f6stem HEAD, etwa zum Ausprobieren\ngit worktree add -d ../projekt-test\n```\n\nFehlt 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.\n\n### git worktree list zeigt alle Arbeitsordner\n\n```bash\ngit worktree list\n```\n\nZuerst steht der Hauptordner, danach die verkn\u00fcpften Worktrees. Zu jedem zeigt Git den Commit und den Branch oder den Vermerk \u201edetached HEAD\u201c. Gesperrte Worktrees sind als \u201elocked\u201c markiert, solche ohne vorhandenen Ordner als \u201eprunable\u201c [1].\n\n### git worktree remove l\u00f6scht nur saubere Worktrees\n\n```bash\ngit worktree remove ../projekt-login\n\n# mit unversionierten oder ge\u00e4nderten Dateien\ngit worktree remove --force ../projekt-login\n```\n\nOhne Zusatz entfernt Git nur einen sauberen Worktree. Sauber hei\u00dft laut Handbuch: keine unversionierten Dateien und keine \u00c4nderungen an versionierten Dateien. F\u00fcr alles andere, und f\u00fcr Worktrees mit Submodulen, braucht es `--force`. Ein gesperrter Worktree verlangt `--force` zweimal. Den Hauptordner kann `remove` gar nicht entfernen [1]. Von einem L\u00f6schen 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\u00f6scht.\n\n### git worktree prune r\u00e4umt nach von Hand gel\u00f6schten Ordnern auf\n\n```bash\ngit worktree prune\n```\n\nWer einen Worktree-Ordner im Dateimanager oder mit `rm -rf` l\u00f6scht, l\u00e4sst Verwaltungsdaten im Repository zur\u00fcck, unter `$GIT_DIR/worktrees`. `prune` entfernt diese Reste f\u00fcr Ordner, die es nicht mehr gibt. Git erledigt das sonst irgendwann von selbst, gesteuert \u00fcber die Einstellung `gc.worktreePruneExpire` [1]. Bis dahin meldet `list` solche Eintr\u00e4ge als \u201eprunable\u201c.\n\n### git worktree lock sch\u00fctzt Worktrees auf externen Laufwerken\n\n```bash\ngit worktree lock --reason \"liegt auf der externen SSD\" ../projekt-archiv\ngit worktree unlock ../projekt-archiv\n```\n\nEin gesperrter Worktree wird nicht beschnitten, nicht verschoben und nicht gel\u00f6scht. Das ist gedacht f\u00fcr Ordner auf Laufwerken, die nicht immer angeschlossen sind. Ohne Sperre k\u00f6nnte `prune` einen solchen Worktree f\u00fcr verschwunden halten [1].\n\nZwei weitere Befehle braucht man seltener: `git worktree move` verschiebt einen Worktree, `git worktree repair` stellt die Verkn\u00fcpfung wieder her, wenn ein Ordner ohne Git umgezogen ist [1].\n\n## Warum brauchen KI-Agenten Worktrees? Zwei Agenten in einem Ordner \u00fcberschreiben sich\n\nEin Ordner hat einen HEAD, einen Index und einen Satz Dateien. Arbeiten zwei Agenten darin, teilen sie alle drei. Das f\u00fchrt zum Beispiel zu diesen St\u00f6rungen:\n\n1. Ein Agent wechselt den Branch. Damit tauscht er die Dateien aus, die der andere gerade bearbeitet.\n2. Beide \u00e4ndern dieselbe Datei. Wer zuletzt speichert, \u00fcberschreibt die \u00c4nderung des anderen.\n3. Ein Agent nimmt mit `git add -A` alle \u00c4nderungen in seinen Commit. Darin landet auch die halbfertige Arbeit des anderen.\n\nMit je einem Worktree hat jeder Agent eigene Dateien, einen eigenen Index und einen eigenen Branch. Das Zusammenf\u00fchren passiert erst, wenn eine Aufgabe fertig ist, \u00fcber einen gew\u00f6hnlichen Merge:\n\n```bash\ngit worktree add -b agent-a ../projekt-agent-a\ngit worktree add -b agent-b ../projekt-agent-b\n# Agent A startet in ../projekt-agent-a, Agent B in ../projekt-agent-b\n\n# sp\u00e4ter, im Hauptordner\ngit merge agent-a\ngit merge agent-b\ngit worktree remove ../projekt-agent-a\ngit branch -d agent-a\n```\n\nWorktrees verhindern keine Merge-Konflikte. \u00c4ndern beide Agenten dieselben Zeilen, meldet Git beim Merge einen Konflikt, genau wie bei zwei Menschen. Was au\u00dferhalb des Ordners liegt, teilen die Agenten weiterhin: eine lokale Datenbank, einen Port f\u00fcr den Entwicklungsserver, Ordner, die per Verkn\u00fcpfung in mehrere Worktrees eingebunden sind. Aufgaben schneidet man deshalb so zu, dass jede einen eigenen Bereich des Projekts betrifft.\n\n## Welche Fallen hat git worktree? Blockiertes L\u00f6schen, mitgel\u00f6schte Ordner, doppelte Branches, fehlende .env\n\n### Eine einzige unversionierte Datei blockiert remove, auch eine .DS_Store\n\nIm Test reichte eine einzige neue, unversionierte Datei, und `git worktree remove` brach mit Exit-Code 128 ab. Die Meldung der deutschen Git-Fassung lautete: \u201eenth\u00e4lt ge\u00e4nderte oder nicht versionierte Dateien, benutzen Sie --force zum L\u00f6schen\u201c [6].\n\nUnter 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\u00fcr Git als unversioniert und blockiert das Entfernen. In einem Fall vom 21.10.2026 lie\u00df sich ein Worktree deshalb erst mit `--force` l\u00f6schen [7].\n\nVor dem L\u00f6schen 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\u00e4chste Abschnitt zeigt.\n\n### git worktree remove l\u00f6scht ignorierte Ordner wie node_modules ohne R\u00fcckfrage\n\nWas 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\u00f6schte den ignorierten Ordner gleich mit [6]. Das Handbuch sagt zu ignorierten Dateien nichts ausdr\u00fccklich [1]. Gepr\u00fcft ist das Verhalten nur mit Git 2.52.0.\n\nF\u00fcr `node_modules` ist das meist gewollt. Gef\u00e4hrlich wird es bei ignorierten Dateien, die sich nicht neu erzeugen lassen, etwa eine `.env` mit Zugangsdaten oder eine lokale Datenbankdatei. Solche Dateien geh\u00f6ren vor dem `remove` aus dem Worktree heraus, denn Git fragt nicht nach.\n\n### Ein Branch l\u00e4sst sich nur in einem Worktree gleichzeitig auschecken\n\n`git worktree add` verweigert einen Branch, der schon in einem anderen Worktree ausgecheckt ist [1]. Im Test lautete die Meldung \u201e'f2' wird bereits von Arbeitsverzeichnis in '/private/tmp/wtt/w2' verwendet\u201c, Exit-Code 128 [6]. Mit `--force` l\u00e4sst sich die Sperre umgehen [1]. Dann teilen sich zwei Ordner wieder einen Branch, was Worktrees gerade vermeiden sollen. F\u00fcr zwei Agenten hei\u00dft das: zwei Branches anlegen, auch wenn beide vom selben Stand ausgehen.\n\nDasselbe gilt f\u00fcr 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\u00fcr einen losgel\u00f6sten HEAD.\n\n### Die .env-Datei fehlt im neuen Worktree\n\nEin neuer Worktree enth\u00e4lt 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\u00e4uft. 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\u00e4chste Abschnitt zeigt.\n\n## Wie arbeitet man mit Worktrees ohne Kommandozeile? Orca legt je Aufgabe einen Worktree mit eigenem Branch an\n\nOrca ist ein quelloffenes Programm unter MIT-Lizenz, das mit Worktrees als Grundeinheit arbeitet [2][3]. Es l\u00e4uft auf macOS (Apple Silicon und Intel), Windows und Linux. F\u00fcr Linux gibt es AppImage, deb, rpm und AUR, jeweils f\u00fcr x64 und arm64. Dazu kommen eine Begleit-App f\u00fcrs Telefon und eine Laufzeit f\u00fcr 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].\n\nSo geht Orca mit Worktrees um, laut Dokumentation [5]:\n\n- Jede Aufgabe bekommt per `git worktree` eine eigene Kopie auf der Platte, mit eigenem Branch und eigenen Terminals f\u00fcr die Agenten.\n- Jedes Repository hat einen Basis-Stand, meist `origin/main`. F\u00fcr jeden Worktree l\u00e4sst sich ein anderer Start w\u00e4hlen: die Basis, ein anderer lokaler Branch, ein Commit oder ein entfernter Branch.\n- Das Anlegen l\u00e4uft im Hintergrund. `git fetch` und `git worktree add` arbeiten weiter, w\u00e4hrend der Dialog schon geschlossen ist.\n- Den Branchnamen leitet Orca aus dem Namen des Arbeitsbereichs ab oder aus einem verkn\u00fcpften Pull Request oder Ticket bei GitHub, Linear, Jira oder GitLab. Bei Linear \u00fcbernimmt es den dort vorgeschlagenen Branchnamen.\n- Von Hand mit `git worktree add` angelegte Worktrees gelten als \u201eextern\u201c, bis man sie in Orca einblendet. Per Skript legt `orca worktree create` einen Worktree an.\n\n### Orca l\u00f6st das Problem fehlender ignorierter Dateien auf drei Wegen\n\nAuch bei Orca ist ein neuer Worktree ein sauberer Checkout ohne ignorierte Dateien. Drei Einstellungen holen sie herein [5]:\n\n1. \u201eWorktree Shared Paths\u201c in den Einstellungen. Auf macOS legt Orca daf\u00fcr einen APFS-Klon an, auf anderen Systemen eine symbolische Verkn\u00fcpfung.\n2. `worktree.sharedDirectories` in der Datei `orca.yaml`. Die genannten Ordner, etwa `node_modules`, werden zwischen den Worktrees geteilt.\n3. Die Datei `.worktreeinclude`. Die dort genannten Dateien, etwa `.env`, werden in jeden neuen Worktree kopiert.\n\nEine kopierte `.env` kann jeder Worktree f\u00fcr sich \u00e4ndern. Ein geteilter Ordner ist dagegen f\u00fcr alle derselbe. Installiert ein Agent darin Pakete, sehen alle anderen das Ergebnis.\n\n### L\u00f6schen in Orca entfernt Ordner und Branch\n\nAnders als `git worktree remove` l\u00f6scht Orca beim Entfernen eines Worktrees Ordner und Branch, nach einer R\u00fcckfrage. Scheitert der Git-Befehl dabei, bietet Orca \u201eForce Delete\u201c an. Beim L\u00f6schen mehrerer Worktrees auf einmal beh\u00e4lt Orca Branches, die noch Commits enthalten, die nicht gemergt sind [5]. In welchem Ordner Orca die Worktrees standardm\u00e4\u00dfig ablegt, steht weder in der Worktree-Dokumentation noch im README [3][5].\n\n## H\u00e4ufige Fragen zu git worktree\n\n### Was ist besser, Worktree oder Branch?\n\nBeides zusammen. Ein Worktree braucht einen Branch, oder einen losgel\u00f6sten HEAD. Ein Branch allein erlaubt nur, nacheinander an verschiedenen St\u00e4nden zu arbeiten. Der Worktree gibt dem Branch einen eigenen Ordner, sodass mehrere St\u00e4nde gleichzeitig offen sind [1].\n\n### Kann man einen Worktree l\u00f6schen, ohne Arbeit zu verlieren?\n\nJa, wenn alles committet ist. Commits liegen im gemeinsamen Repository, nicht im Ordner, und `git worktree remove` l\u00f6scht den Branch nicht [1]. Verloren gehen nicht committete \u00c4nderungen und unversionierte Dateien, sobald `--force` im Spiel ist. Ignorierte Dateien wie `.env` oder `node_modules` l\u00f6schte `remove` im Test sogar ohne `--force` mit [6]. Orca l\u00f6scht zus\u00e4tzlich den Branch, beh\u00e4lt beim Sammell\u00f6schen aber Branches mit nicht gemergten Commits [5].\n\n### Kann derselbe Branch in zwei Worktrees ausgecheckt sein?\n\nNein, nicht ohne `--force`. Git lehnt einen Branch ab, der bereits in einem anderen Worktree ausgecheckt ist [1][6].\n\n### Was passiert, wenn man einen Worktree-Ordner einfach l\u00f6scht?\n\nDer Ordner ist weg, im Repository bleiben Verwaltungsdaten zur\u00fcck. `git worktree list` zeigt den Eintrag als \u201eprunable\u201c, `git worktree prune` r\u00e4umt ihn auf [1]. Der Branch bleibt erhalten.\n\n### Brauchen zwei KI-Agenten im selben Repository zwei Branches?\n\nJa. Ein Branch l\u00e4sst sich nur in einem Worktree auschecken [1]. Jeder Agent bekommt deshalb einen eigenen Worktree mit eigenem Branch. Fertige Arbeit kommt \u00fcber einen Merge zur\u00fcck in den Hauptbranch.\n\n## Quellen zu git worktree und Orca, abgerufen am 03.11.2026\n\n1. Git-Handbuch: git-worktree, zuletzt ge\u00e4ndert in Git 2.56.0 (28.09.2026). https://git-scm.com/docs/git-worktree\n2. GitHub-API: Repository stablyai/orca (Lizenz, Homepage). https://api.github.com/repos/stablyai/orca\n3. GitHub: stablyai/orca, README. https://github.com/stablyai/orca/blob/main/README.md\n4. GitHub: stablyai/orca, aktuelle Ver\u00f6ffentlichung v1.4.247 (03.11.2026). https://github.com/stablyai/orca/releases/latest\n5. Orca-Dokumentation: Worktrees. https://www.onorca.dev/docs/model/worktrees\n6. 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\u00f6ffentlicht.\n7. Eigene Beobachtung vom 21.10.2026 unter macOS: `.DS_Store` blockiert `git worktree remove`. Nicht ver\u00f6ffentlicht.",
    "sig": "92c8972a191d00545c826aa6eb18cd683da117fd26390e27499e1dc269d972119276f91471cf458ff856da2d2ae40bb085b55f7b4dcbc36c66f604594a09e010"
}