Git Worktree: Parallel an mehreren Branches arbeiten

1. Das Problem: Stash und Branch-Wechsel kosten Zeit und Kontext

Der klassische Git-Alltag sieht so aus: Man arbeitet an einem Feature, ein dringender Bug-Report kommt rein, und plötzlich muss man mit git stash den aktuellen Stand beiseiteschieben, auf main wechseln, den Hotfix bauen, testen, mergen, zurück auf den Feature-Branch wechseln und den Stash wieder einspielen. Jeder dieser Schritte ist eine potenzielle Fehlerquelle: vergessene Stashes, versehentlich committete halbfertige Änderungen oder ein composer install, das nach jedem Wechsel erneut läuft, weil sich composer.lock zwischen den Branches unterscheidet.

Bei Magento-Projekten verschärft sich das Problem zusätzlich: Ein Branch-Wechsel kann bedeuten, dass generierte Dateien in generated/, der statische Content in pub/static und teilweise sogar der Datenbankstand nicht mehr zum ausgecheckten Code passen. Wer dann bin/magento setup:upgrade vergisst, jagt Fehlermeldungen, die gar nichts mit dem eigentlichen Bug zu tun haben. Das Grundproblem ist immer dasselbe: Ein einzelnes Arbeitsverzeichnis kann zu jedem Zeitpunkt nur einen Branch-Zustand abbilden.

Git Worktree löst dieses Problem strukturell, indem es mehrere Arbeitsverzeichnisse an ein einziges Repository koppelt. Jedes Verzeichnis hat seinen eigenen ausgecheckten Branch, seinen eigenen Stand der Working Directory und Staging Area, teilt sich aber Objektdatenbank, Konfiguration und Commit-Historie mit den anderen Worktrees. Der Hotfix läuft in einem eigenen Ordner, das Feature bleibt unangetastet im anderen, und kein git stash ist mehr nötig.

2. git worktree add, list und remove im Überblick

Der Befehl git worktree add <pfad> <branch> erstellt ein neues Arbeitsverzeichnis am angegebenen Pfad und checkt dort den angegebenen Branch aus. Existiert der Branch noch nicht, erzeugt -b <neuer-branch> ihn direkt beim Anlegen des Worktrees, ausgehend vom aktuellen HEAD oder einem explizit angegebenen Startpunkt. Der neue Ordner verhält sich wie ein vollständiges Repository: git status, git log, git diff funktionieren dort völlig normal, nur eben isoliert vom Hauptverzeichnis.

git worktree list zeigt alle aktiven Worktrees mit ihrem Pfad, dem aktuellen Commit und dem ausgecheckten Branch an, eine kompakte Übersicht besonders dann wichtig, wenn mehrere parallele Verzeichnisse existieren und man den Überblick behalten muss. Zum Entfernen eines nicht mehr benötigten Worktrees dient git worktree remove <pfad>, das sowohl den Verzeichniseintrag in Git als auch den physischen Ordner löscht, sofern keine uncommitteten Änderungen vorhanden sind. Mit --force lässt sich das notfalls erzwingen, sollte aber bewusst und nicht routinemäßig eingesetzt werden.

# Neues Worktree-Verzeichnis für einen bestehenden Branch anlegen
git worktree add ../shop-hotfix hotfix/checkout-crash

# Neuen Branch direkt beim Anlegen des Worktrees erstellen
git worktree add -b feature/wishlist-export ../shop-wishlist origin/main

# Alle aktiven Worktrees mit Pfad, Commit und Branch auflisten
git worktree list
# /home/dev/shop            a1b2c3d [main]
# /home/dev/shop-hotfix     e4f5g6h [hotfix/checkout-crash]
# /home/dev/shop-wishlist   h7i8j9k [feature/wishlist-export]

# Nicht mehr benötigtes Worktree-Verzeichnis entfernen
git worktree remove ../shop-hotfix

3. Praxisfall: Hotfix testen, während das Feature mitten in der Arbeit steckt

Der häufigste Anwendungsfall für Worktrees im Entwickleralltag: Ein Feature ist zu 60 Prozent fertig, mehrere Dateien sind verändert, aber noch nicht in einem sauberen Zustand für einen Commit. Gleichzeitig meldet der Support einen kritischen Fehler in der Kasse, der sofort behoben werden muss. Statt den halbfertigen Stand zu stashen und das Risiko einzugehen, ihn später zu vergessen oder falsch wieder einzuspielen, legt man einfach einen zweiten Worktree an, checkt dort main aus und erstellt den Hotfix-Branch.

Der entscheidende Vorteil: Beide Verzeichnisse existieren gleichzeitig auf der Festplatte, beide sind vollständig funktionsfähig, und man kann jederzeit zwischen ihnen wechseln, indem man einfach das Terminal-Fenster oder den geöffneten Editor-Ordner wechselt, ganz ohne Git-Befehl. Der Feature-Stand bleibt exakt so erhalten, wie er war, inklusive uncommitteter Änderungen, offener Editor-Tabs und laufender Docker-Container, falls jeder Worktree eine eigene Compose-Konfiguration nutzt.

Nach dem Hotfix wird der Branch regulär gemerged und der temporäre Worktree wieder entfernt. Wichtig ist dabei, dass beide Worktrees dieselbe Commit-Historie und dieselben Remote-Referenzen sehen, ein git fetch in einem Worktree macht neue Commits sofort in allen anderen sichtbar, da sie sich die Objektdatenbank teilen.

# Während im Hauptverzeichnis ein Feature halbfertig ist:
# neuen Worktree für den dringenden Hotfix anlegen
git worktree add -b hotfix/checkout-crash ../shop-hotfix origin/main
cd ../shop-hotfix

# Hotfix entwickeln, testen, committen
git add src/app/code/Mironsoft/Checkout/Model/PaymentValidator.php
git commit -m "Fix null pointer in payment validator on empty cart"

# Zurück ins Hauptverzeichnis, Hotfix von dort mergen
cd ../shop
git merge hotfix/checkout-crash

# Worktree nicht mehr nötig, aufräumen
git worktree remove ../shop-hotfix

4. Lange Builds und Testsuiten laufen lassen, während woanders weitercodiert wird

Magento-Testsuiten, insbesondere Integrationstests oder ein voller bin/magento setup:di:compile-Lauf, können mehrere Minuten bis hin zu einer Viertelstunde dauern. Klassisch blockiert das die Working Directory: Während der Build läuft, kann man den Branch nicht wechseln, ohne den Lauf abzubrechen oder inkonsistente Ergebnisse zu riskieren. Mit einem zweiten Worktree lässt sich der lange Prozess in einem eigenen Verzeichnis anstoßen, während im Hauptverzeichnis normal weitercodiert wird.

Das ist besonders wertvoll bei CI-ähnlichen lokalen Läufen: PHPUnit-Suiten, PHPStan auf Level 5 über ein ganzes Modul, oder ein kompletter Tailwind-Build mit anschließendem setup:static-content:deploy. All diese Prozesse binden CPU und I/O, blockieren aber nicht mehr den eigentlichen Editier-Workflow, weil sie in einem physisch getrennten Verzeichnis mit eigenem Dateisystemzustand laufen.

Ein praktisches Muster: einen dauerhaften Worktree namens shop-ci anlegen, der immer auf dem aktuellen Feature-Branch steht und ausschließlich für lange Prüfläufe genutzt wird. Nach jedem git push im Hauptverzeichnis reicht dort ein git pull, um den Prüflauf mit dem neuesten Stand zu starten, während im Hauptverzeichnis bereits am nächsten Commit gearbeitet wird.

# Dauerhaften Worktree für lange Testläufe anlegen
git worktree add ../shop-ci feature/wishlist-export
cd ../shop-ci

# Langen Lauf im Hintergrund starten, Hauptverzeichnis bleibt frei
bin/analyse app/code/Mironsoft/Wishlist --level=5 &
bin/magento setup:di:compile

# Im Hauptverzeichnis parallel weiterarbeiten, unabhängig vom Lauf
cd ../shop
git add src/app/code/Mironsoft/Wishlist/Model/ExportProcessor.php
git commit -m "Add CSV export chunking for large wishlists"

5. Pull Requests in eigenen Worktrees reviewen

Ein Pull Request lokal zu reviewen bedeutet klassisch, den eigenen Arbeitsstand zu stashen, den PR-Branch auszuchecken, den Code manuell durchzuklicken oder im Editor zu öffnen, und danach wieder zurückzuwechseln. Mit einem eigenen Review-Worktree entfällt dieser Umweg komplett: git worktree add ../shop-review origin/pr-branch checkt den Branch in einem separaten Ordner aus, der Editor öffnet diesen Ordner als eigenes Projekt, und der eigentliche Arbeitsstand bleibt komplett unberührt.

Dieses Muster eignet sich besonders für Reviews, bei denen man den Code tatsächlich lokal ausführen möchte, etwa um eine UI-Änderung im Browser zu prüfen oder einen Hyvä-Alpine.js-Baustein interaktiv zu testen, statt sich nur auf das Diff im Pull-Request-Interface zu verlassen. Da der Review-Worktree ein eigenständiges Verzeichnis ist, kann dort sogar ein eigener Docker-Container mit eigenem Port laufen, während der reguläre Entwicklungscontainer im Hauptverzeichnis unbeeinflusst weiterläuft.

Nach abgeschlossenem Review wird der Worktree einfach entfernt, ohne dass jemals der eigene Branch-Kontext verlassen werden musste. Bei häufigen Reviews lohnt sich ein feststehender Ordner wie shop-review, der bei jedem neuen PR mit git worktree remove und erneutem git worktree add wiederverwendet wird, statt jedes Mal einen neuen Pfad zu wählen.

6. Einschränkungen: ein Branch pro Worktree, gemeinsames .git-Verzeichnis

Die wichtigste Einschränkung von Git Worktree: Derselbe Branch kann nicht gleichzeitig in zwei Worktrees ausgecheckt sein. Git verhindert das aktiv mit einer Fehlermeldung, weil zwei parallele Arbeitsverzeichnisse mit demselben Branch unweigerlich zu widersprüchlichen HEAD-Zuständen führen würden. Wer denselben Branch in einem zweiten Verzeichnis nur betrachten möchte, ohne ihn zu bearbeiten, kann stattdessen einen losgelösten Zustand mit git worktree add --detach auf dem gewünschten Commit anlegen.

Alle Worktrees teilen sich dasselbe .git-Verzeichnis im Hauptrepository, in den zusätzlichen Worktrees liegt lediglich eine .git-Datei mit einem Verweis auf das eigentliche Verzeichnis. Das bedeutet: Objektdatenbank, Konfiguration, Remotes und Hooks werden geteilt, aber Index, HEAD und der Merge-Zustand sind pro Worktree getrennt. Löscht man das Hauptverzeichnis versehentlich, reißt man alle abhängigen Worktrees mit, deshalb sollte das ursprüngliche Klon-Verzeichnis nie leichtfertig entfernt werden.

Zusätzlicher Speicherplatz ist ein weiterer Faktor: Jeder Worktree benötigt eine vollständige Kopie der Working Directory, bei Magento-Projekten mit vendor/, generated/ und pub/static schnell mehrere Gigabyte pro Verzeichnis. Die Objektdatenbank selbst wird nicht dupliziert, aber die tatsächlich ausgecheckten Dateien schon, was bei vielen parallelen Worktrees relevanten Plattenplatz kostet.

7. Magento- und PHP-spezifische Stolperfallen: vendor, Docker, .env

Der größte praktische Stolperstein bei Magento-Projekten: vendor/ wird nicht über Git verwaltet und existiert in jedem neuen Worktree zunächst gar nicht. Nach git worktree add ist deshalb fast immer ein eigenständiges bin/composer install im neuen Verzeichnis nötig, was bei großen Abhängigkeitsbäumen mehrere Minuten dauert. Wer das häufig macht, profitiert von einem lokalen Composer-Cache-Verzeichnis, das über alle Worktrees hinweg wiederverwendet wird und wiederholte Downloads spart.

Auch .env-Dateien, lokale docker-compose.override.yml-Anpassungen und generierte Verzeichnisse wie generated/ oder var/ sind typischerweise via .gitignore ausgeschlossen und müssen pro Worktree separat gepflegt werden. Bei Mark-Shust-Docker-Setups bedeutet das konkret: Jeder Worktree braucht entweder einen eigenen Projektnamen und eigene Ports in der Compose-Konfiguration, oder die Container werden bewusst sequenziell genutzt, ein Worktree gestoppt, bevor der nächste hochgefahren wird.

Ein bewährtes Muster für Magento-Teams: pro Worktree eine eigene .env mit abweichendem COMPOSE_PROJECT_NAME und verschobenen Ports, sowie ein eigener Datenbank-Container oder zumindest eine eigene Datenbank innerhalb eines gemeinsam genutzten MySQL-Containers. So lässt sich der Hotfix-Worktree gegen einen produktionsnahen Datenbestand testen, während der Feature-Worktree weiterhin mit Testdaten arbeitet, ohne dass sich beide gegenseitig stören.

# Neuen Worktree anlegen und Magento-spezifische Abhängigkeiten nachziehen
git worktree add ../shop-hotfix hotfix/checkout-crash
cd ../shop-hotfix

# vendor/ existiert hier noch nicht, muss separat installiert werden
bin/composer install

# Eigene .env mit abweichendem Projektnamen und Ports für Docker
cp ../shop/.env .env
sed -i 's/COMPOSE_PROJECT_NAME=shop/COMPOSE_PROJECT_NAME=shop_hotfix/' .env
sed -i 's/WEBSERVER_PORT=80/WEBSERVER_PORT=8081/' .env

bin/start
bin/magento setup:upgrade

8. Aufräumen: prune, lock und das Entfernen alter Worktrees

Worktrees, deren Verzeichnis manuell gelöscht wurde, statt sie mit git worktree remove ordentlich zu entfernen, hinterlassen verwaiste Einträge in der internen Verwaltung von Git. git worktree prune räumt diese verwaisten Referenzen auf, indem es prüft, welche registrierten Worktree-Pfade physisch nicht mehr existieren, und die zugehörigen Metadaten entfernt. Das ist besonders nach manuellem Aufräumen im Dateisystem oder nach dem Löschen eines temporären Branches ein sinnvoller Routine-Schritt.

Für Worktrees, die versehentlich nicht gelöscht werden sollen, etwa weil dort gerade ein wichtiger Testlauf aktiv ist, bietet git worktree lock <pfad> Schutz: Ein gesperrter Worktree lässt sich nicht versehentlich mit remove oder prune entfernen, bis er explizit mit git worktree unlock wieder freigegeben wird. Das ist vor allem bei Worktrees auf externen oder Netzlaufwerken relevant, wo Git das Verzeichnis nicht immer zuverlässig als vorhanden erkennt.

Für den Alltag empfiehlt sich eine einfache Routine: Nach jedem abgeschlossenen Hotfix oder Review sofort git worktree remove ausführen, statt Worktrees anzusammeln. Regelmäßig git worktree list zur Kontrolle laufen lassen zeigt zuverlässig, welche Verzeichnisse noch aktiv sind, bevor unnötig Speicherplatz und Übersicht verloren gehen.

# Verwaiste Worktree-Einträge aufräumen, z.B. nach manuellem rm -rf
git worktree prune -v

# Wichtigen Worktree vor versehentlichem Entfernen schützen
git worktree lock ../shop-ci --reason "Langer Testlauf aktiv"

# Sperre wieder aufheben, sobald der Lauf fertig ist
git worktree unlock ../shop-ci

# Aktuellen Stand aller Worktrees kontrollieren
git worktree list --porcelain

9. Worktree im Vergleich zu Stash, Clone und Branch-Wechsel

Es gibt vier gängige Wege, um mit mehreren Branch-Zuständen gleichzeitig zu arbeiten: klassischer Branch-Wechsel mit git checkout, temporäres Zwischenspeichern mit git stash, ein vollständiger zusätzlicher Klon des Repositories, oder eben Git Worktree. Jeder Ansatz hat einen klaren Trade-off zwischen Geschwindigkeit, Speicherplatz und Risiko, den die folgende Tabelle zusammenfasst.

In der Praxis ist git worktree für alle Fälle die überlegene Lösung, in denen mehrere Zustände desselben Repositories gleichzeitig gebraucht werden: Hotfix neben Feature, langer Testlauf neben aktiver Entwicklung, PR-Review neben eigenem Code. Stash bleibt für sehr kurze, wenige-Sekunden-Unterbrechungen sinnvoll, ein zusätzlicher Full Clone lohnt sich nur, wenn tatsächlich komplett unabhängige Remote-Konfigurationen benötigt werden.

10. Zusammenfassung

Git Worktree löst ein Problem, das jeder Entwickler kennt: mehrere Branches gleichzeitig bearbeiten, ohne Stash, ohne Kontextverlust und ohne blockierte Working Directory. Mit git worktree add entsteht ein eigenständiges Verzeichnis pro Branch, das sich Objektdatenbank und Commit-Historie mit dem Hauptrepository teilt. Praktisch zeigt sich der Nutzen überall dort, wo klassische Workflows an ihre Grenzen stoßen: ein Hotfix neben einem halbfertigen Feature, ein langer Testlauf neben aktiver Entwicklung, ein Pull-Request-Review ohne den eigenen Arbeitsstand zu unterbrechen.

Wer Worktrees produktiv einsetzt, muss zwei Regeln beachten: Derselbe Branch kann nie in zwei Worktrees gleichzeitig ausgecheckt sein, und jeder Worktree braucht bei Magento-Projekten eine eigene vendor/-Installation sowie gegebenenfalls eine eigene Docker-Konfiguration mit abweichenden Ports. Mit git worktree list, prune und lock lässt sich die Verwaltung mehrerer paralleler Verzeichnisse zuverlässig und ohne Datenverlust im Griff behalten.

11. FAQ: Git Worktree