Parallele Entwicklung mit Git Worktrees

Das Problem mit dem Kontextwechsel

Du steckst tief in einem Feature-Branch. Drei Dateien geöffnet, ein mentales Modell des Datenflusses im Kopf, Tests halb geschrieben. Dann kommt ein kritischer Bug-Report. Irgendwas ist in Produktion kaputt.

Der klassische Workflow: Änderungen stashen, Branch wechseln, mentalen Kontext verlieren, den Bug fixen, committen, zurückwechseln, den Stash popen – und hoffen, dass der Stash sauber applied und sich das mentale Modell irgendwie wieder zusammensetzt. Meistens verbringst du zwanzig Minuten damit, wieder dahin zu kommen, wo du vor der Unterbrechung warst.

Git Worktrees lösen genau das auf der primitiven Ebene. Anstatt Branches in einem einzelnen Verzeichnis zu wechseln, erstellst du ein zweites Arbeitsverzeichnis, das auf einen anderen Branch desselben Repositories zeigt. Zwei Branches, zwei Verzeichnisse, kein Stashing. Deine Feature-Arbeit bleibt genau dort, wo du sie zurückgelassen hast.

Das Problem ist, dass Worktrees zwar einfach zu erstellen, aber schmerzhaft zu konfigurieren sind – besonders in einem Monorepo.

Warum Worktrees in Monorepos schwierig sind

Ein Turborepo-Monorepo mit pnpm Workspaces fügt Komplexitätsebenen hinzu, die ein einfaches git worktree add nicht abdeckt:

• Shared Packages müssen gebaut werden. Die Produkt-App hängt von kompilierten Ausgaben der Shared Packages ab (@nextsaasai/ui, @nextsaasai/utils, @nextsaasai/blog). Ein frischer Worktree hat keine dist/-Verzeichnisse – nichts kompiliert, bis du die Build-Pipeline laufen lässt.
• Mehrere Environment-Dateien. Das Monorepo benötigt .env.local-Dateien auf drei Ebenen: Repository-Root, apps/boilerplate/ und apps/marketing/. Fehlt eine davon, fehlen zur Laufzeit Environment-Variablen.
• Port-Konflikte. Zwei Next.js Dev-Server können nicht auf demselben Port lauschen. Jeder Worktree braucht seine eigene Port-Konfiguration – aber Next.js liest PORT nicht aus .env.local. Der Commander.js CLI-Parser läuft, bevor @next/env die Environment-Variablen lädt.
• Dev-Script-Patching. Der einzig zuverlässige Weg, den Port zu setzen, ist das --port-CLI-Flag. Das bedeutet, dass jeder Worktree seine package.json-Dev-Scripts mit der richtigen Port-Nummer gepatcht haben muss.
• Cleanup-Komplexität. git worktree remove räumt ungetrackte Dateien wie .turbo/daemon/ nicht auf, die Turborepo anlegt. Übrig gebliebene Verzeichnisse verursachen Fehler beim Erstellen künftiger Worktrees mit demselben Namen.

Jedes dieser Probleme ist in fünf Minuten lösbar. Alle zusammen – jedes Mal, wenn du einen parallelen Workspace willst – summieren sich auf dreißig Minuten manueller Konfiguration, die den Sinn von Worktrees vollständig zunichte macht.

Die Automatisierung, die wir gebaut haben

Der nextsaas.ai Worktree-Befehl übernimmt den kompletten Lebenszyklus – Erstellung, Konfiguration und Cleanup – in einem einzigen Schritt:

1. Branch-Erkennung. Identifiziert automatisch den Parent-Branch für den Worktree, standardmäßig der aktuelle Branch oder per expliziter Angabe.
2. Verzeichnis-Erstellung. Erstellt den Worktree an einem vorhersehbaren Ort relativ zum Haupt-Repository, mit einer Namenskonvention, die das Auffinden von Worktrees einfach macht.
3. Port-Zuweisung. Berechnet eindeutige Ports basierend auf der Position des Worktrees (Basis-Port + Offset) und patcht apps/boilerplate/package.json und apps/marketing/package.json mit den richtigen --port-Flags.
4. Environment-Setup. Kopiert alle .env.local-Dateien vom Haupt-Repository in den Worktree und passt Port-Referenzen in jeder Datei an.
5. Dependency-Installation. Führt pnpm install im Worktree aus, um sicherzustellen, dass die Lockfile respektiert wird.
6. Package-Build. Führt pnpm build für Shared Packages aus, damit Anwendungs-Imports sofort auflösen.
7. Git-Cleanup-Flags. Markiert die gepatchten package.json-Dateien mit --skip-worktree, sodass sie nicht als modifiziert in git status erscheinen.

Das Entfernen ist gleichermaßen automatisiert. Der Cleanup-Befehl führt git worktree remove aus und folgt dann mit rm -rf auf das Verzeichnis, um ungetrackte Dateien zu beseitigen, die Gits Worktree-Entfernung absichtlich zurücklässt.

KI-Coding in parallel

Die eigentliche Motivation hinter dieser Automatisierung war nicht der klassische Entwickler-Workflow – sondern KI-unterstützte Entwicklung.

Mehrere KI-Coding-Sessions gegen dasselbe Arbeitsverzeichnis laufen zu lassen, schafft ein grundlegendes Problem: Schreibkonflikte. Zwei Sessions, die überlappende Dateien bearbeiten, korrumpieren gegenseitig ihre Arbeit. Das ist kein theoretisches Risiko – es passiert in dem Moment, wo beide Sessions ein gemeinsames Utility, eine Config-Datei oder ein Test-Suite berühren. Je mehr Sessions du parallel laufen lässt, desto schlimmer werden die Konflikte.

Worktrees beseitigen das vollständig. Jede KI-Coding-Session bekommt ihr eigenes Verzeichnis, ihren eigenen Dev-Server, ihren eigenen Git-State. Schreibkonflikte sind ausgeschlossen, weil jede Session auf einer physisch getrennten Kopie der Codebase arbeitet. Ein Refactoring im Shared UI-Package kann in einem Worktree laufen, während ein neuer API-Endpoint in einem anderen entwickelt wird – dasselbe Repository, dieselbe Git-History, vollständige Isolation.

Der Workflow-Vorteil potenziert sich von dort aus. Du startest einen zweiten Workspace in unter einer Minute, und die Feature-Session läuft ungestört weiter, während die Hotfix-Session unabhängig arbeitet. Wenn der Fix deployed ist, entfernst du den Worktree und machst genau dort weiter, wo du aufgehört hast. Als Bonus bleibt der angesammelte Kontext jeder Session erhalten – die Dateien, die sie gelesen hat, die Muster, die sie gelernt hat, die bereits ausprobierten Ansätze – anstatt durch einen Branch-Wechsel oder Stash-Zyklus verloren zu gehen.

Übertragbare Muster

Die spezifische Automatisierung, die wir gebaut haben, ist auf unser Turborepo + pnpm Monorepo zugeschnitten. Aber die Muster übertragen sich auf jedes Monorepo-Setup:

Worktree-Automatisierung muss alles abdecken, was ein frischer Clone abdecken würde – Environment-Dateien, Port-Konfiguration, Dependency-Installation und Package-Builds. Wenn du jemandem kein leeres git worktree add-Verzeichnis in die Hand drücken und sagen würdest „ruf einfach npm start auf", dann hat dein Worktree-Tooling Lücken.

Der --skip-worktree-Trick für gepatchte Dateien ist universell nützlich. Jede Datei, die Pro-Worktree-Modifikationen braucht (Port-Configs, Environment-Overrides), sollte für git status unsichtbar sein, damit Entwickler und CI-Tools einen sauberen Working Tree sehen.