Claude Code mit Git Worktrees nutzen

1. Warum Git Worktrees fuer Claude Code relevant sind

Wer mit Claude Code an mehreren unabhaengigen Aufgaben gleichzeitig arbeiten will, stoesst schnell auf ein Problem: Ein einzelnes Arbeitsverzeichnis kann zu jedem Zeitpunkt nur einen einzigen Branch ausgecheckt haben. Ein Git Worktree loest genau das, indem er aus demselben Repository ein zweites, drittes oder viertes eigenstaendiges Arbeitsverzeichnis erzeugt, jedes mit seinem eigenen Branch, aber alle greifen auf dieselbe zugrunde liegende Git-Historie zu. Fuer Claude Code bedeutet das: mehrere Sessions koennen parallel an unterschiedlichen Branches arbeiten, ohne dass eine Session die andere durch einen Branch-Wechsel stoert.

Der praktische Wert zeigt sich besonders bei Aufgaben, die parallel laufen sollen, aber unterschiedliche Codezustaende benoetigen: ein Hotfix an der Produktionsversion, waehrend gleichzeitig an einem grossen Feature auf einem anderen Branch gearbeitet wird, oder ein Code-Review-Durchlauf an einem Pull-Request-Branch, waehrend die eigene Entwicklung ungestoert weiterlaeuft. Ohne Git Worktrees muesste man staendig zwischen Branches wechseln, mit dem Risiko, unfertige Aenderungen zu stashen oder versehentlich zu vermischen.

2. Grundlagen: Worktree versus Branch-Wechsel

Ein klassischer Branch-Wechsel mit git checkout oder git switch aendert den Inhalt desselben Arbeitsverzeichnisses, alle Dateien werden ausgetauscht, der vorherige Zustand existiert nur noch in Git selbst. Ein Git Worktree dagegen erzeugt ein komplett separates Verzeichnis auf der Festplatte, mit einem eigenen, gleichzeitig ausgecheckten Branch. Beide Verzeichnisse teilen sich dasselbe .git-Objektverzeichnis im Hintergrund, sodass Commits, Branches und die komplette Historie zwischen ihnen sichtbar sind, ohne dass Daten dupliziert werden muessen.

Der entscheidende Unterschied zu einem vollstaendigen zweiten Klon des Repositories: Ein Git Worktree teilt sich die Objektdatenbank, ein zweiter Klon dagegen dupliziert die komplette Historie auf der Festplatte. Bei einem grossen Repository mit vielen Jahren Historie kann das den Unterschied zwischen wenigen Megabyte fuer einen zusaetzlichen Worktree und mehreren Gigabyte fuer einen kompletten zweiten Klon ausmachen. Diese Effizienz macht Git Worktrees zur naheliegenden Wahl fuer temporaere, parallele Arbeitsverzeichnisse.

3. Einen Worktree fuer eine parallele Aufgabe anlegen

Der Befehl git worktree add erzeugt in einem Schritt ein neues Verzeichnis und checkt darin einen Branch aus, entweder einen bestehenden oder einen neu erstellten. Der Pfad zum neuen Verzeichnis sollte klar erkennbar sein, etwa als Geschwisterverzeichnis des Hauptrepositories mit dem Branch-Namen im Pfad. Claude Code kann dann direkt in diesem neuen Verzeichnis gestartet werden, mit eigenem Kontext, eigener CLAUDE.md-Sicht und eigenem Arbeitsstand, komplett unabhaengig vom Hauptverzeichnis.

Fuer eine neue Aufgabe, die noch keinen eigenen Branch hat, erstellt git worktree add -b gleichzeitig einen neuen Branch und den zugehoerigen Worktree in einem einzigen Befehl. Diese Kombination ist besonders praktisch fuer schnell startende Parallelaufgaben: statt erst einen Branch zu erstellen und dann manuell dorthin zu wechseln, entsteht die komplette isolierte Arbeitsumgebung in einem Schritt.

# Starting point: main repository at ~/projects/mironsoft
cd ~/projects/mironsoft

# Create a worktree for an existing branch (e.g. reviewing a PR)
git worktree add ../mironsoft-review-pr-42 origin/feature/checkout-redesign

# Create a worktree AND a new branch in one step (typical for a fresh task)
git worktree add -b feature/new-payment-method ../mironsoft-new-payment-method

# Start Claude Code inside the new, isolated worktree
cd ../mironsoft-new-payment-method
claude

4. Mehrere Claude-Code-Instanzen gleichzeitig betreiben

Da jeder Git Worktree ein eigenstaendiges Verzeichnis ist, laesst sich in jedem davon eine eigene Claude-Code-Instanz starten, jede mit ihrem eigenen Terminalfenster, ihrem eigenen Konversationskontext und ihrem eigenen Arbeitsstand. Eine Instanz kann an einem Hotfix arbeiten, waehrend eine zweite Instanz parallel ein neues Feature entwickelt und eine dritte einen Pull-Request-Branch reviewt, alle drei vollstaendig unabhaengig voneinander und ohne sich gegenseitig zu beeinflussen.

Diese Parallelitaet auf Dateisystem-Ebene ist der zentrale Vorteil gegenueber dem Versuch, mehrere Aufgaben in einer einzigen Claude-Code-Session mit staendigem Branch-Wechsel zu jonglieren. Jede Instanz sieht konsistent nur den Code-Stand ihres eigenen Branches, es gibt keine Verwirrung darueber, welcher Zustand gerade aktiv ist, und ein Fehler in einer Instanz, etwa ein kaputter Build, beeinflusst die anderen Instanzen in ihren eigenen Worktrees nicht.

5. Abhaengigkeiten und Build-Artefakte pro Worktree isolieren

Eine haeufige Falle beim Einsatz mehrerer Git Worktrees: Verzeichnisse wie node_modules oder vendor werden von Git nicht versioniert und existieren deshalb in jedem Worktree separat. Das ist grundsaetzlich korrekt und notwendig, denn unterschiedliche Branches koennen unterschiedliche Abhaengigkeitsversionen erfordern, bedeutet aber auch, dass nach dem Anlegen eines neuen Worktrees ein eigener Installationsschritt noetig ist, etwa npm install oder composer install, bevor der Code lauffaehig ist.

Fuer Projekte mit sehr grossen Abhaengigkeitsverzeichnissen lohnt sich ein Package-Manager mit globalem Cache, etwa pnpm oder ein Composer-Cache-Verzeichnis, das ueber alle Worktrees hinweg geteilt wird. So muessen Pakete nicht bei jedem neuen Worktree komplett neu heruntergeladen werden, nur die symbolischen Verknuepfungen im jeweiligen node_modules-Verzeichnis werden pro Worktree neu erstellt. Das reduziert die Zeit vom Anlegen eines Worktrees bis zur ersten lauffaehigen Umgebung erheblich.

#!/usr/bin/env bash
# setup-worktree.sh -- installs dependencies using a shared global cache
set -euo pipefail

WORKTREE_DIR="$1"
cd "$WORKTREE_DIR"

# Composer: shared cache directory across all worktrees, no re-download
composer config -g cache-dir "$HOME/.cache/composer-shared"
composer install --no-interaction

# npm/pnpm: pnpm's content-addressable store avoids duplicating packages
if [[ -f package.json ]]; then
  pnpm install --prefer-offline
fi

echo "Worktree at $WORKTREE_DIR is ready"

6. Worktrees auflisten, entfernen und aufraeumen

Mit der Zeit sammeln sich in einem aktiven Projekt mehrere Git Worktrees an, deshalb ist regelmaessige Verwaltung wichtig. Der Befehl git worktree list zeigt alle aktiven Worktrees mit Pfad und ausgecheckten Branch, sodass jederzeit ein Ueberblick besteht, welche parallelen Arbeitsstaende gerade existieren. Ist eine Aufgabe abgeschlossen und der zugehoerige Branch gemerged, entfernt git worktree remove das Verzeichnis sauber, inklusive der Verknuepfung im internen Git-Metadatenverzeichnis.

Wird ein Worktree-Verzeichnis versehentlich manuell mit rm -rf geloescht, statt den korrekten Befehl zu nutzen, bleibt ein verwaister Eintrag in Gits interner Verwaltung zurueck. Der Befehl git worktree prune raeumt genau solche verwaisten Referenzen auf und sollte routinemaessig nach manuellem Aufraeumen ausgefuehrt werden, um die interne Worktree-Liste konsistent zu halten.

# List all active worktrees with their path and checked-out branch
git worktree list
# /home/user/projects/mironsoft            abc1234 [main]
# /home/user/projects/mironsoft-hotfix-88  def5678 [hotfix/TICKET-88]
# /home/user/projects/mironsoft-new-payment ghi9012 [feature/new-payment-method]

# Remove a worktree once its branch has been merged
git worktree remove ../mironsoft-hotfix-88

# Clean up stale references after a manual directory deletion
git worktree prune -v

7. Typischer Workflow: Feature, Hotfix und Review parallel

Ein realistischer Tagesablauf mit Git Worktrees und Claude Code sieht oft so aus: Die Hauptarbeit an einem groesseren Feature laeuft im Hauptverzeichnis auf einem Feature-Branch. Meldet sich in der Zwischenzeit ein dringender Produktionsfehler, entsteht statt eines riskanten Zwischenspeicherns der Feature-Aenderungen einfach ein neuer Worktree fuer den Hotfix-Branch, ausgehend vom aktuellen Produktions-Tag. Claude Code arbeitet in diesem isolierten Verzeichnis am Fix, waehrend der Feature-Fortschritt im Hauptverzeichnis komplett unberuehrt bleibt.

Parallel dazu kann ein dritter Worktree fuer einen eingehenden Pull-Request angelegt werden, um dessen Aenderungen lokal zu testen und mit Claude Code strukturiert zu reviewen, ohne den eigenen Arbeitsstand ueberhaupt zu beruehren. Nach Abschluss jeder dieser drei Aufgaben wird der jeweilige Worktree entfernt, waehrend die anderen beiden unveraendert weiterlaufen. Dieses Muster aus Feature, Hotfix und Review parallel ist der haeufigste praktische Anwendungsfall fuer Git Worktrees in Verbindung mit Claude Code.

# A realistic day: feature work, an urgent hotfix, and a PR review, all in parallel

# Main directory stays on the feature branch, untouched
cd ~/projects/mironsoft   # branch: feature/checkout-redesign

# Urgent production bug arrives -- spin up an isolated hotfix worktree
git worktree add -b hotfix/TICKET-88 ../mironsoft-hotfix-88 origin/main
cd ../mironsoft-hotfix-88 && claude   # fix runs here, feature work untouched

# A PR needs review -- a third, read-mostly worktree
cd ~/projects/mironsoft
git worktree add ../mironsoft-review-pr-42 origin/feature/other-teammate-branch
cd ../mironsoft-review-pr-42 && claude   # review runs here

# All three working states coexist without interfering with each other
git worktree list

8. Fallstricke: geteiltes .git-Verzeichnis und Locking

Weil alle Git Worktrees desselben Repositories sich dieselbe interne Objektdatenbank teilen, sind bestimmte Operationen nicht gleichzeitig in mehreren Worktrees sicher moeglich. Zwei Worktrees koennen niemals denselben Branch gleichzeitig auschecken, Git verhindert das explizit mit einer Fehlermeldung. Auch bestimmte interne Git-Operationen wie ein Rebase oder ein interaktives Umschreiben der Historie sollten nicht in einem Worktree laufen, waehrend gleichzeitig in einem anderen Worktree auf denselben Commits gearbeitet wird, weil sich sonst die referenzierten Commit-Hashes waehrend der laufenden Operation aendern koennen.

Ein zweiter praktischer Fallstrick ist der Speicherort: Worktrees sollten als Geschwisterverzeichnisse ausserhalb des Hauptrepository-Pfads liegen, nicht als Unterverzeichnis innerhalb des Hauptrepositories, sonst kann Git das verschachtelte Verzeichnis faelschlich als Teil des Hauptrepository-Inhalts interpretieren. Ein dritter Fallstrick betrifft IDE-Konfiguration und Editor-Einstellungen, die oft projektspezifisch, aber nicht Teil des Git-Repositories sind, hier lohnt sich ein kleines Setup-Skript, das nach dem Anlegen eines neuen Worktrees automatisch Editor-Konfigurationsdateien kopiert.

# Git explicitly refuses to check out the same branch in two worktrees
git worktree add ../mironsoft-second-copy feature/checkout-redesign
# fatal: 'feature/checkout-redesign' is already checked out at
#        '/home/user/projects/mironsoft'

# Correct: create a new branch from the same starting point instead
git worktree add -b feature/checkout-redesign-copy ../mironsoft-second-copy \
  feature/checkout-redesign

9. Worktrees im Vergleich zu Branch-Wechsel und Klonen

Fuer parallele Arbeit an mehreren Branches gibt es drei grundsaetzliche Ansaetze, deren Vor- und Nachteile sich direkt gegenueberstellen lassen.

Ein zweiter vollstaendiger Klon bietet dieselbe Isolation wie ein Git Worktree, kostet aber deutlich mehr Speicherplatz und Zeit beim Anlegen, weil die komplette Historie dupliziert wird. Ein einfacher Branch-Wechsel ist am schnellsten eingerichtet, verhindert aber jede Form paralleler Arbeit an mehreren Branches gleichzeitig. Git Worktrees vereinen die Vorteile beider Extreme: nahezu ebenso sparsam wie ein einfacher Branch-Wechsel, aber mit vollstaendiger Isolation eines zweiten Klons.

10. Zusammenfassung

Git Worktrees loesen ein konkretes Problem beim Einsatz von Claude Code an mehreren parallelen Aufgaben: Ein einzelnes Arbeitsverzeichnis kann nur einen Branch gleichzeitig auschecken, ein Worktree erzeugt dagegen ein zusaetzliches, vollstaendig isoliertes Verzeichnis mit geteilter Git-Historie. Das erlaubt mehrere gleichzeitige Claude-Code-Instanzen an unterschiedlichen Branches, jede mit eigenem Kontext und eigenem Arbeitsstand, ohne dass Branch-Wechsel unfertige Aenderungen gefaehrden.

Abhaengigkeiten wie node_modules muessen pro Worktree separat installiert werden, ein globaler Package-Cache reduziert den Mehraufwand deutlich. Regelmaessiges Aufraeumen mit git worktree remove und git worktree prune haelt die Verwaltung sauber. Im Vergleich zu einem zweiten vollstaendigen Klon sind Git Worktrees deutlich sparsamer, im Vergleich zu einfachem Branch-Wechsel bieten sie echte Parallelitaet ohne Kompromisse.

11. FAQ: Claude Code mit Git Worktrees nutzen