Git Worktrees erklärt: Wann und warum Sie sie einsetzen sollten

Ein Git-Worktree ist ein zusätzliches Arbeitsverzeichnis, das an dasselbe Repository angebunden ist und einen eigenen ausgecheckten Branch besitzt. So können Sie zwei Branches gleichzeitig in zwei Ordnern geöffnet halten, ohne etwas klonen zu müssen.

Die meisten Entwicklerinnen und Entwickler stoßen mitten in einer Frustration auf diesen Bedarf: ein Stash, der auf dem falschen Branch angewendet wurde, ein Language Server, der sich nach einem Checkout durch eine Neuindizierung quält, oder ein zweiter Klon desselben Repos, der nie so recht synchron bleibt. Worktrees lösen alle drei Probleme – und sie sind seit Git 2.5 im Juli 2015 fester Bestandteil von Git, es muss also nichts installiert werden.

Dieser Artikel behandelt, was ein Worktree auf der Festplatte tatsächlich ist, die drei Befehle, mit denen das Feature funktioniert, wann er einem Stash überlegen ist, wann er einen zweiten Klon schlägt – und welchen Preis Sie dafür zahlen.

Was ist ein Git-Worktree auf der Festplatte?

Ein verlinkter Worktree ist ein Verzeichnis mit ausgecheckten Dateien, keine Kopie Ihres Repositories. Sein .git auf oberster Ebene ist eine einfache Datei, kein Verzeichnis, und verweist auf einen kleinen Metadaten-Ordner unterhalb von .git/worktrees/ im Haupt-Repository – ein Layout, das die git-worktree-Dokumentation vollständig beschreibt. Alles Schwergewichtige bleibt an einem Ort: eine Objektdatenbank, eine Historie und ein Satz von Refs bedienen sämtliche Worktrees, und nur eine Handvoll Dateien gehört zu einem einzelnen Worktree, darunter HEAD und der Index.

Diese eine Tatsache erklärt alles Weitere über Worktrees. Einen anzulegen kostet ein Checkout, keinen Klon. Commits, die in irgendeinem Worktree entstehen, sind sofort aus jedem anderen sichtbar, weil darunter nur ein einziges Repository liegt.

Welchen Workflow ersetzt ein Worktree?

Ohne Worktrees bedeutet eine dringende Unterbrechung, dass Sie Ihren aktuellen Zustand aussetzen müssen. Die bekannte Abfolge, hier mit der git stash push-Form, damit die Nachricht auch tatsächlich hängen bleibt:

git stash push -m "wip: login form"
git checkout main
git checkout -b hotfix-bug
# fix, commit, push, wait for the merge
git checkout feature-login
git stash pop

Fünf Befehle, zwei Kontextwechsel und eine Gelegenheit, den Stash auf dem falschen Branch zu poppen. Die Worktree-Variante ist ein einziger Befehl:

git worktree add -b hotfix-bug ../hotfix-workspace main

Das legt einen Nachbarordner an, erstellt den Branch hotfix-bug ausgehend von main und checkt ihn dort aus. Ihr ursprüngliches Verzeichnis bleibt unberührt: derselbe Branch, dieselben geänderten Dateien, derselbe geöffnete Editor. Sobald der Fix gemergt ist, löscht git worktree remove ../hotfix-workspace den Ordner und meldet ihn ab.

Die drei Befehle: add, list, remove

Der tägliche Umgang mit Worktrees läuft über drei Unterbefehle. git worktree add <path> <branch> checkt einen bestehenden Branch an einem neuen Pfad aus; ergänzen Sie -b <new-branch> vor dem Pfad, um den Branch gleich mit anzulegen. Zeigt add auf einen Pfad, der noch nicht existiert, legt Git das Verzeichnis für Sie an.

git worktree list zeigt jeden Worktree an – den Haupt-Worktree zuerst – mit Pfad, abgekürztem Commit-Hash und ausgechecktem Branch in Klammern:

/home/you/project             abc1234 [feature-login]
/home/you/hotfix-workspace    def5678 [hotfix-bug]

git worktree remove <path> löscht einen Worktree, und Gits Regeln zum Entfernen sind streng: Eine einzige nicht versionierte Datei oder eine bearbeitete versionierte Datei stoppt den Befehl, sofern Sie nicht --force ergänzen – womit diese Änderungen verworfen werden. Den Haupt-Worktree gibt Git überhaupt nicht frei, und ein gesperrter benötigt --force zweimal. Wenn Sie einen Worktree-Ordner stattdessen von Hand löschen, räumt git worktree prune die zurückgebliebenen Metadaten auf.

Wann schlägt ein Worktree einen Stash?

Ein Stash setzt Ihre Arbeit aus; ein Worktree lässt sie weiterlaufen. Dieser Unterschied entscheidet, was Sie brauchen. Ein Stash ist völlig in Ordnung, um ein Zwei-Zeilen-Diff für zehn Minuten wegzulegen. Er ist das falsche Werkzeug, wenn die Arbeit in Ihrem Verzeichnis noch in Bewegung ist: eine laufende Test-Suite oder ein langer Build, ein Dev-Server, der Dateien beobachtet, oder ein Editor, dessen Language Server nach einem Branch-Wechsel das gesamte Projekt neu indizieren würde.

Mit einem Worktree wird nichts davon gestört, weil Sie das ursprüngliche Verzeichnis nie anfassen. Sie öffnen den neuen Ordner in einem zweiten Editorfenster, erledigen dort die störende Aufgabe und kommen zurück, um alles genau so vorzufinden, wie Sie es verlassen haben. Dieselbe Isolation ist der Grund, warum Tools, die KI-Coding-Agents parallel ausführen, Worktrees als Arbeitsmodell übernommen haben. Für eine pointiertere Sichtweise beschreibt matklads Beitrag das feste Set aus fünf Worktrees eines Entwicklers, die eher parallelen Tätigkeiten als Branches zugeordnet sind; betrachten Sie das als persönliches Setup, nicht als gängige Praxis.

Worktree oder zweiter Klon?

Ein Worktree schlägt einen zweiten Klon immer dann, wenn beide Verzeichnisse dasselbe Repository verfolgen sollen. Weil sich alle Worktrees einen Objektspeicher und einen Satz von Refs teilen, aktualisiert ein einziges git fetch sie alle, ein aus einem Worktree gepushter Branch ist sofort in den anderen sichtbar, und das Hinzufügen eines Worktrees dupliziert keine Historie auf der Festplatte. Ein zweiter Klon bietet nichts davon: zwei Objektspeicher, in die gefetcht werden muss, zwei Ref-Sätze, die auseinanderdriften, und doppelter Speicherverbrauch.

Ein Klon ist in zwei Fällen weiterhin die richtige Wahl: wenn die Arbeit zu einem tatsächlich anderen Remote gehört, etwa einem Fork, mit dem Sie separat interagieren, oder wenn Sie ein Wegwerf-Experiment vollständig von Ihrem Haupt-Repository isolieren wollen, bei dem selbst geteilte Refs unerwünscht sind.

Was kosten Worktrees?

Git verfolgt committete Dateien, nicht Ihre Umgebung. Das ist der wesentliche Preis jedes neuen Worktrees:

• Installierte Abhängigkeiten kommen nicht mit. Ein frischer Worktree eines npm- oder pip-Projekts braucht in der Regel einen eigenen Installationsschritt, bevor er baut.
• Nicht versionierte lokale Dateien bleiben zurück: .env-Dateien, lokale Konfiguration und Build-Caches liegen alle im ursprünglichen Verzeichnis, weil Git nichts von ihnen weiß.
• Worktree-Ordner, die innerhalb des Repos angelegt werden, tauchen als nicht versionierter Ballast auf und brauchen einen .gitignore-Eintrag. Nachbarverzeichnisse (../hotfix-workspace) vermeiden das Problem vollständig.
• Standardmäßig kann ein Branch nur in einem Worktree gleichzeitig ausgecheckt sein. Es gibt Umgehungen (--force bei add, --ignore-other-worktrees bei switch), aber die sauberere Antwort, wenn Sie einen Commit nur bauen oder testen wollen, ist ein Worktree mit detached HEAD:

git worktree add -d ../build-check 1a2b3c4

Das Flag -d belässt HEAD im neuen Ordner im Detached-Zustand, sodass kein Branch beansprucht wird und die Einschränkung nie greift. git switch -d <commit> innerhalb eines bestehenden Worktrees erledigt dasselbe.

Haben Sie genug parallel am Laufen?

Der Test für die Einführung ist kurz. Kommen Unterbrechungen regelmäßig genau dann, wenn Sie echte, nicht committete Arbeit in Bearbeitung haben? Löst ein Branch-Wechsel eine Neuinstallation von Abhängigkeiten oder eine spürbare Language-Server-Neuindizierung aus? Pflegen Sie bereits einen zweiten Klon desselben Repositories? Zwei Ja – und Worktrees machen sich in der ersten Woche bezahlt. Kein einziges Ja – dann sind Stash plus Branches wirklich völlig in Ordnung. Fangen Sie mit einem an: Wenn das nächste Mal ein dringender Fix mitten in einem Feature hereinkommt, führen Sie git worktree add statt git stash aus und entfernen Sie den Ordner, sobald der Fix gemergt ist.

FAQs

Funktionieren Git-Worktrees mit Repositories, die Submodule verwenden?

Teilweise. Gits eigenes Handbuch kennzeichnet die Submodul-Unterstützung im BUGS-Abschnitt als unfertig und rät davon ab, ein Superprojekt an mehr als einer Stelle gleichzeitig auszuchecken. In der Praxis lässt sich ein verlinkter Worktree mit Submodulen darin nicht mit git worktree move verschieben, und das Entfernen mit git worktree remove erfordert das Force-Flag. Wenn Ihr Repository stark auf Submodule setzt, ist ein zweiter Klon die sicherere Wahl.

Werden Stashes und Branches zwischen Git-Worktrees geteilt?

Ja. Alles unterhalb von refs/ ist allen Worktrees gemeinsam, sodass Branches, Tags und der Stash überall gleich aussehen, wo immer Sie stehen. Drei Namensräume sind die Ausnahme und bleiben lokal auf einen Worktree beschränkt: refs/bisect, refs/worktree und refs/rewritten. Darüber hinaus sind nur die eigenen Zeiger eines Worktrees privat, darunter HEAD und sein Index. Ein Stash, den Sie in einem Worktree anlegen, kann daher aus jedem anderen Worktree desselben Repositories aufgelistet und gepoppt werden.

Kann ich einen Worktree nach dem Anlegen in einen anderen Ordner verschieben?

Ja. Übergeben Sie git worktree move den Worktree und den gewünschten Pfad, und Git verschiebt den Ordner und schreibt dessen Metadaten in einem Zug um. Zwei Fälle bewältigt es nicht: den Haupt-Worktree und jeden verlinkten Worktree mit Submodulen darin. Ein gesperrter Worktree benötigt das Force-Flag zweimal. Wenn Sie den Ordner bereits selbst irgendwohin verschoben haben, stellt git worktree repair die Verbindung wieder her.

Was passiert, wenn ich git worktree add nur mit einem Pfad und ohne Branch ausführe?

Git nimmt den letzten Teil des Pfads als Branch-Namen, startet diesen Branch bei HEAD und checkt ihn im neuen Ordner aus. git worktree add ../hotfix hinterlässt Ihnen also einen Branch namens hotfix, ausgecheckt unter ../hotfix. Ist dieser Name bereits vergeben, checkt Git stattdessen den bestehenden Branch aus – sofern kein anderer Worktree ihn gerade belegt.