using-git-worktrees

Überblick

Was ist using-git-worktrees?

using-git-worktrees ist ein Workflow-Skill aus dem Repository obra/superpowers, das dich Schritt für Schritt beim Anlegen isolierter Git-Worktrees für Feature-Entwicklung unterstützt. Es standardisiert, wie und wo Worktrees erzeugt werden, sodass du sicher parallel an mehreren Branches arbeiten kannst, ohne ständig in einem einzigen Working Directory hin- und herzuschalten.

Anstatt manuell zu raten, wo Worktrees liegen sollten, oder das Risiko einzugehen, nicht getrackte und nicht ignorierte Verzeichnisse zu erzeugen, kodiert dieses Skill einen klaren Prozess zur Verzeichnisauswahl und -prüfung. Das Ziel ist verlässliche Isolation für Implementierungsarbeit, während dein Hauptprojekt-Baum sauber bleibt.

Für wen ist dieses Skill gedacht?

Dieses Skill richtet sich an Entwickler:innen, die:

• an mehreren Features oder Fixes parallel arbeiten,
• eine wiederholbare Git-Worktree-Konvention über Projekte hinweg wollen,
• sicher sein möchten, dass Worktree-Verzeichnisse korrekt platziert sind und keine Commits verschmutzen,
• Git auf der Kommandozeile nutzen und sich mit einfachen Shell-Kommandos wohlfühlen.

Es passt besonders gut zu Teams, die einen dokumentierten, konsistenten Git-Workflow und eine sicherere Möglichkeit suchen, temporäre oder langlebige Feature-Umgebungen aufzusetzen.

Welche Probleme löst using-git-worktrees?

using-git-worktrees hilft dir, typische Probleme bei der Arbeit mit mehreren Branches zu vermeiden:

• Overhead beim Branch-Wechsel: Arbeite gleichzeitig an mehreren Branches, ohne ständig stashen und neu auschecken zu müssen.
• Unübersichtliche Projekt-Roots: Verhindere, dass spontane Verzeichnisse und Worktree-Ordner irgendwo im Dateisystem verstreut werden.
• Unbeabsichtigte Commits von Worktree-Ordnern: Der Flow legt Wert darauf, zu prüfen, dass lokale Worktree-Verzeichnisse ignoriert werden, bevor du sie anlegst.
• Inkonsistente Konventionen über Maschinen hinweg: Durch das Prüfen bestehender Verzeichnisse und optionaler Präferenzen in CLAUDE.md führt dich das Skill zu einem standardisierten Layout pro Projekt.

Wenn du Git-Worktrees regelmäßig nutzt oder sicher damit starten willst, bietet dir dieses Skill ein leichtgewichtiges, wohldefiniertes Vorgehen.

Wann ist using-git-worktrees besonders sinnvoll?

Du solltest using-git-worktrees verwenden, wenn:

• du mit Feature-Arbeit beginnst, die von deinem aktuellen Workspace isoliert sein muss,
• du eine Implementierung basierend auf einem bestehenden Design oder Plan umsetzen willst und dafür einen sauberen Worktree nutzen möchtest,
• dein Repository bereits .worktrees- oder worktrees-Verzeichnisse verwendet und du diese Konvention fortführen willst.

Weniger hilfreich ist es, wenn:

• du immer nur an einem einzigen Branch arbeitest und keine mehreren Arbeitskopien brauchst,
• du bereits ein strenges, automatisiertes internes Tool einsetzt, das Worktrees auf andere Weise verwaltet.

In allen anderen Fällen kann der using-git-worktrees-Flow deinen Git-Workflow vorhersehbarer und sicherer machen.

Verwendung

Installation und Setup

Um das Skill using-git-worktrees in deiner Umgebung zu nutzen, installiere es aus dem Repository obra/superpowers:

npx skills add https://github.com/obra/superpowers --skill using-git-worktrees

Nach der Installation:

1. Öffne die Datei skills/using-git-worktrees/SKILL.md in deinem Repository-Checkout.
2. Lies sie einmal vollständig durch, um den Ablauf zur Verzeichnisauswahl und den Sicherheitsprüfungen zu verstehen.
3. Stelle sicher, dass du dich in einem Git-Repository befindest, in dem du zusätzliche Worktree-Verzeichnisse anlegen möchtest.

Du benötigst keine weiteren Abhängigkeiten außer Git und einer Shell, die die in der Skill-Beschreibung gezeigten Kommandos ausführen kann.

Kern-Workflow: Isolierte Feature-Arbeit starten

Wenn du neue Feature-Arbeit beginnst und einen isolierten Workspace möchtest, folge dem übergeordneten Flow, den using-git-worktrees definiert:

1. Workflow ankündigen (für dich selbst und evtl. Assistenten oder Tools):

   "I'm using the using-git-worktrees skill to set up an isolated workspace."

2. Worktree-Verzeichnis bestimmen mithilfe des Verzeichnisauswahl-Prozesses (siehe nächster Abschnitt). Das verhindert, dass Worktrees an beliebigen, unübersichtlichen Pfaden landen.

3. Sicherheitsprüfung durchführen, passend zum gewählten Verzeichnistyp (projektlokal vs. global). Dieser Schritt ist entscheidend, um unbeabsichtigte Commits von Worktree-Ordnern zu vermeiden.

4. Git-Worktree für den benötigten Branch anlegen. Zum Beispiel:

   git worktree add <path-to-worktree> <branch-name>
   

5. In den neuen Worktree wechseln und deine Implementierungsarbeit dort durchführen. Deine ursprüngliche Arbeitskopie bleibt damit sauber und verfügbar für Code-Reviews, schnelle Fixes oder andere Aufgaben.

Wiederhole diesen Flow immer dann, wenn du ein neues Feature, einen Spike oder ein Experiment startest, das deinen aktuellen Working Directory nicht beeinflussen soll.

Prozess zur Verzeichnisauswahl

using-git-worktrees definiert eine klare Reihenfolge zur Verzeichnisauswahl, damit du immer weißt, wo Worktrees hingehören und die Entscheidung nicht jedes Mal neu treffen musst.

1. Bevorzugt bestehende Worktree-Verzeichnisse nutzen

Prüfe im Root deines Repositories auf bevorzugte Worktree-Verzeichnisse in folgender Priorität:

ls -d .worktrees 2>/dev/null     # Preferred (hidden)
ls -d worktrees 2>/dev/null      # Alternative

• Wenn .worktrees existiert, verwende dieses Verzeichnis.
• Wenn .worktrees nicht existiert, aber worktrees vorhanden ist, verwende worktrees.
• Wenn keines von beiden existiert, gehe zum nächsten Schritt.

Diese Regel sorgt dafür, dass dein Workflow mit bisherigen Entscheidungen im selben Projekt konsistent bleibt.

2. CLAUDE.md auf Projekt-Präferenzen prüfen

Wenn kein Standard-Worktree-Verzeichnis vorhanden ist, suche im Projekt-Root nach dokumentierten Präferenzen in CLAUDE.md:

grep -i "worktree.*director" CLAUDE.md 2>/dev/null

Wenn CLAUDE.md eine Worktree-Verzeichnis-Konvention vorgibt, verwende diese ohne weitere Rückfragen. So kann ein Projekt sein bevorzugtes Worktree-Layout zentral dokumentieren.

3. Neuen Speicherort wählen, wenn keine Präferenz existiert

Wenn es weder ein bestehendes Verzeichnis noch eine dokumentierte Präferenz in CLAUDE.md gibt, wähle explizit, wo neue Worktrees liegen sollen. Das Skill schlägt vor, dir selbst (oder deinem Team) eine klare Auswahl anzubieten:

No worktree directory found. Where should I create worktrees?

1. .worktrees/ (project-local, hidden)
2. ~/.config/superpowers/worktrees/<project-name>/ (global location)

Which would you prefer?

• Option 1: .worktrees/ hält die Worktrees direkt beim Projekt, standardmäßig versteckt und im Repo leicht auffindbar.
• Option 2: ~/.config/superpowers/worktrees/<project-name>/ zentralisiert Worktrees pro Projekt außerhalb des Repo-Roots. Das ist hilfreich, wenn dein Git-Working-Directory optisch möglichst schlank bleiben soll.

Sobald du eine Option gewählt hast, solltest du für dasselbe Projekt bei diesem Speicherort bleiben, um Fragmentierung zu vermeiden.

Sicherheitsprüfungen vor dem Anlegen eines Worktrees

Das using-git-worktrees-Skill legt besonderen Wert auf Sicherheitschecks, vor allem bei projektlokalen Verzeichnissen, die innerhalb des Git-Repositories liegen.

Prüfen, dass projektlokale Verzeichnisse ignoriert werden

Für projektlokale Verzeichnisse wie .worktrees oder worktrees musst du sicherstellen, dass sie von Git ignoriert werden, bevor du darin Worktrees anlegst. Das Skill markiert dies als MUSS-Bedingung.

Mindestens solltest du:

• überprüfen, dass .worktrees oder worktrees in einer relevanten Ignore-Datei (.gitignore, .git/info/exclude oder globalen Ignore-Dateien) aufgeführt ist, und
• git check-ignore verwenden, um sicherzugehen, dass Git das Verzeichnis in deiner aktuellen Konfiguration tatsächlich ignoriert.

Ein typisches Prüfmuster ist, git check-ignore gegen den Verzeichnispfad auszuführen und zu bestätigen, dass Git diesen als ignoriert behandelt – unter Berücksichtigung lokaler, globaler und systemweiter Ignore-Einstellungen.

Wenn das Verzeichnis nicht ignoriert wird:

• füge es in einer passenden Ignore-Datei hinzu, commite die Ignore-Regel, falls sie ins Repository gehört, und
• führe die Prüfung erneut aus, bevor du dort Worktrees anlegst.

So reduzierst du das Risiko, dass deine Worktree-Infrastruktur versehentlich gestaged oder committed wird.

Globale Speicherorte sicher verwenden

Wenn du die globale Verzeichnisoption wählst (z. B. unter ~/.config/superpowers/worktrees/), liegen diese Verzeichnisse außerhalb des Repositories und werden von Git nicht getrackt. In diesem Fall ist die Ignore-Anforderung weniger kritisch, trotzdem solltest du sicherstellen, dass:

• der Pfad über deine Maschinen hinweg stabil ist (oder für Teammitglieder dokumentiert wird),
• ausreichend Speicherplatz für mehrere vollständige Worktrees vorhanden ist.

Wenn du diese Prüfschritte konsequent anwendest, bleibt deine Git-Historie auf Quellcode-Änderungen fokussiert, statt von Tool-Artefakten überlagert zu werden.

Das Skill an deinen Workflow anpassen

Das using-git-worktrees-Skill ist bewusst leichtgewichtig und repository-zentriert gehalten. So kannst du es in deinen größeren Workflow integrieren:

• Dokumentiere deine endgültige Wahl des Worktree-Verzeichnisses in den Contribution- oder Onboarding-Dokumenten deines Projekts.
• Erwäge, einen kurzen Abschnitt in CLAUDE.md hinzuzufügen, der beschreibt, wie dein Team Git-Worktrees verwendet.
• Wenn du ein Ein-Kommando-Setup möchtest, kannst du die Schritte zur Verzeichnisauswahl und Verifizierungen in eigene Shell-Skripte kapseln, wobei die ursprünglichen Regeln weiterhin die maßgebliche Referenz bleiben.

Das Skill versteht sich als klare Referenz-Implementierung, der du entweder direkt folgen oder die du kontrolliert an deine Umgebung anpassen kannst.

FAQ

Was ist der Hauptvorteil von using-git-worktrees gegenüber normalen Git-Checkouts?

using-git-worktrees erleichtert paralleles Arbeiten an mehreren Branches, indem zusätzliche Arbeitsverzeichnisse (Worktrees) erzeugt werden, die sich dieselbe Git-Historie teilen. Statt in einem einzelnen Verzeichnis immer wieder zu checken und zu stashen, hat jedes Feature oder jeder Fix seinen eigenen isolierten Workspace – geleitet von einem konsistenten Prozess zur Verzeichnisauswahl und zu Sicherheitsprüfungen.

Wie installiere ich das Skill using-git-worktrees?

Installiere das Skill aus dem Repository obra/superpowers mit:

npx skills add https://github.com/obra/superpowers --skill using-git-worktrees

Öffne nach der Installation skills/using-git-worktrees/SKILL.md in deinem lokalen Checkout, um den detaillierten Workflow nachzuvollziehen.

Muss ich meinen bestehenden Git-Workflow ändern, um dieses Skill zu nutzen?

Du musst deinen gesamten Workflow nicht umstellen. using-git-worktrees konzentriert sich darauf, wie du isolierte Workspaces startest und verwaltest. Du kannst weiterhin wie gewohnt committen, rebasen und pushen; das Skill standardisiert in erster Linie, wo und wie du Worktrees anlegst und stellt sicher, dass sie sicher platziert sind.

Kann ich using-git-worktrees mit jedem Git-Repository verwenden?

Ja, solange das Repository grundsätzlich mit Git-Worktrees kompatibel ist. Das Skill nutzt Standard-Git-Kommandos und Shell-Utilities. Für die besten Ergebnisse solltest du die Verzeichnisprüfungen aus dem Repository-Root heraus ausführen und die Ignore-Empfehlungen für projektlokale Worktree-Verzeichnisse befolgen.

Was ist, wenn mein Projekt bereits eine andere Worktree-Konvention nutzt?

Wenn dein Projekt bereits .worktrees, worktrees oder eine in CLAUDE.md dokumentierte Konvention verwendet, übernimmt using-git-worktrees diese Präferenz automatisch über die Verzeichnisauswahl-Regeln. Wenn deine Konvention völlig anders ist, kannst du die Grundprinzipien (klare Verzeichnisauswahl und Sicherheitschecks) trotzdem übernehmen und auf dein bestehendes Layout anwenden.

Ist using-git-worktrees für große oder langlebige Projekte geeignet?

Ja. Das Skill ist besonders hilfreich für große Projekte, in denen mehrere langlaufende Branches üblich sind. Die strukturierte Verzeichnisauswahl und der Fokus auf Ignore-Regeln helfen, dein Repository langfristig organisiert zu halten – auch dann, wenn sich viele Worktrees für laufende Arbeiten ansammeln.

Wann sollte ich auf using-git-worktrees verzichten?

Dieses Skill brauchst du möglicherweise nicht, wenn du selten an mehr als einem Branch gleichzeitig arbeitest oder wenn dein Team bereits ein anderes dediziertes Tool einsetzt, das Worktrees verwaltet und eigene Verzeichnis-Konventionen erzwingt. In solchen Fällen bringt die zusätzliche Struktur von using-git-worktrees möglicherweise zu wenig Mehrwert, um deine bestehenden Gewohnheiten zu ändern.

Wo finde ich die ursprüngliche Definition dieses Skills?

Die autoritative Definition von using-git-worktrees befindet sich in der Datei SKILL.md im Verzeichnis skills/using-git-worktrees des GitHub-Repositories obra/superpowers. Konsultiere diese Datei für die präziseste und aktuellste Verhaltensbeschreibung.