git-worktree-manager
von alirezarezvanigit-worktree-manager unterstützt parallele Git Worktrees mit isolierten Branches, deterministischen Ports, `.env`-Dateisynchronisierung, optionaler Dependency-Installation und Cleanup-Prüfungen. Dieser Skill eignet sich für Multi-Agent- oder Multi-Branch-Git-Workflows, die lokale Apps sicherer voneinander trennen müssen.
Dieser Skill erreicht 82/100 Punkte und ist damit ein solider Kandidat für Verzeichnisnutzer, die sicherere parallele Git-Worktree-Workflows benötigen. Er bietet ausreichend konkrete Tools, Befehle und Referenzen, damit ein Agent zuverlässiger arbeiten kann als mit einem allgemeinen Prompt. Nutzer sollten jedoch die uneinheitlichen Installationspfade und die Hinweise auf experimentellen/WIP-Status beachten.
- Sehr gut auslösbar: Beschreibung und Anwendungsfälle zielen klar auf parallele Branches, Multi-Agent-Arbeit, isolierte Dev-Server und die Isolation experimenteller Branches ab.
- Der praktische Nutzen wird durch echte Skripte gestützt: Worktree-Erstellung, deterministische Portvergabe, `.env*`-Synchronisierung, optionale Dependency-Installation, Prüfung veralteter/dirty/merged Worktrees und sicheres Cleanup.
- Gutes unterstützendes Material für den Einstieg: README-Quick-Start-Befehle sowie Referenzen zu Portvergabe und Docker-Compose-Worktree-Mustern verringern das Rätselraten für Agents.
- Die Installationspfade im README wirken im Vergleich zum Repository-Pfad uneinheitlich: Dort steht `engineering/git-worktree-manager`, während der Skill unter `engineering/skills/git-worktree-manager` liegt.
- Strukturelle Hinweise wie `wip`/`experimental` deuten darauf hin, dass Nutzer das Verhalten im eigenen Repository prüfen sollten, bevor sie sich auf die Cleanup-Automatisierung verlassen.
Überblick über den git-worktree-manager Skill
Was git-worktree-manager macht
git-worktree-manager ist ein Engineering-Skill, mit dem du mehrere lokale Git worktrees parallel betreiben kannst, ohne Konflikte bei Branches, Ports, Umgebungen oder Aufräumarbeiten zu riskieren. Der Skill kombiniert praktische Arbeitsanleitungen mit Python-Hilfsskripten, die vorbereitete worktrees anlegen, deterministische Ports zuweisen, lokale Umgebungsdateien kopieren, optional Abhängigkeiten installieren und veraltete worktrees vor dem Entfernen prüfen.
Nutze diesen Skill, wenn einfache git worktree-Befehle nicht mehr ausreichen, weil sich jeder Branch wie eine eigene lokal ausführbare App verhalten soll.
Am besten geeignet für parallele Git-Workflows
Am besten passt der Skill zu Entwickler:innen, Tech Leads oder Betreiber:innen von Coding-Agents, die zwei oder mehr Branches gleichzeitig offenhalten: Feature-Entwicklung, Hotfixes, PR-Reviews, Migrationstests oder Multi-Agent-Implementierungen. git-worktree-manager for Git Workflows ist besonders nützlich, wenn jeder Agent oder jede Terminal-Session einen eigenen Branch und eine isolierte Laufzeitumgebung bekommen soll, statt sich ein einziges Checkout zu teilen.
Weniger Mehrwert bringt der Skill, wenn du nur gelegentlich zwischen Branches wechselst, keine lokalen Services startest oder bereits einen ausgereiften internen Wrapper für worktrees nutzt.
Wichtige Unterschiede vor der Installation
Der praktische Nutzen besteht nicht nur darin, „einen worktree anzulegen“. Der Skill ergänzt wiederholbare Konventionen für:
- deterministische Benennung von worktrees und Branch-Erstellung
- überschneidungsfreie Port-Zuweisung für App, Datenbank und Redis
- Synchronisierung von
.env,.env.local,.env.developmentund.envrc - Erkennung von Dependency-Installationen anhand gängiger Lockfiles
- Prüfungen für veraltete, dirty und bereits gemergte Branches vor dem Aufräumen
- Docker Compose-Muster für isolierte Services pro worktree
Damit ist der git-worktree-manager skill stärker auf den Betrieb im Alltag ausgelegt als ein allgemeiner Prompt zu Git worktrees.
So verwendest du den git-worktree-manager Skill
Installationsoptionen für git-worktree-manager
Für ein Claude-ähnliches Skills-Setup installierst du den Skill aus dem Repository, sofern dein Skill-Manager das unterstützt:
npx skills add alirezarezvani/claude-skills --skill git-worktree-manager
Bei manueller Installation kopierst du das Skill-Verzeichnis aus:
engineering/skills/git-worktree-manager
in deinen lokalen Skills-Ordner, zum Beispiel ~/.claude/skills/git-worktree-manager, ~/.codex/skills/git-worktree-manager oder ein anderes kompatibles Agent-Skill-Verzeichnis. Prüfe nach der Installation, ob diese Dateien vorhanden sind: SKILL.md, README.md, scripts/worktree_manager.py, scripts/worktree_cleanup.py sowie die beiden Dateien unter references/.
Diese Dateien solltest du zuerst lesen
Für einen schnellen Einstieg lies die Dateien in dieser Reihenfolge:
README.mdfür die Befehlsstruktur und die Tool-Übersicht.SKILL.mdfür den vorgesehenen Workflow und Hinweise, wann der Skill sinnvoll ist.references/port-allocation-strategy.md, bevor du Service-Ports änderst.references/docker-compose-patterns.md, falls deine App Compose verwendet.scripts/worktree_manager.pyundscripts/worktree_cleanup.py, bevor du die Automatisierung in einem Produktions-Repository nutzt.
Das ist wichtig, weil die Skripte echte Checkouts verändern, env-Dateien kopieren und gegebenenfalls Abhängigkeiten installieren. Prüfe die Defaults, bevor du sie in einem großen Monorepo oder in einem Repository mit sensibler lokaler Konfiguration ausführst.
Praktische Nutzung von git-worktree-manager
Ein typischer Ablauf zum Erstellen und Vorbereiten sieht so aus:
python scripts/worktree_manager.py \
--repo . \
--branch feature/api-hardening \
--name wt-api-hardening \
--base-branch main \
--install-deps \
--format text
Ein Ablauf zur Aufräumprüfung sieht so aus:
python scripts/worktree_cleanup.py \
--repo . \
--stale-days 14 \
--format text
Beide Tools unterstützen JSON-Eingaben über --input <json-file> oder stdin, was für Automatisierung hilfreich ist. Bitte den Agenten zuerst um einen Befehlsplan und führe das Skript erst aus, nachdem du Repository-Pfad, Branch-Name, Base-Branch, Verhalten bei Dependency-Installation und Cleanup-Regeln bestätigt hast.
Prompt-Muster für bessere Ergebnisse
Schwacher Prompt:
Set up a worktree for my feature.
Stärkerer Prompt:
Use
git-worktree-managerto prepare a new worktree for branchfeature/billing-webhooksfrommainin repo/Users/me/app. Name itwt-billing-webhooks. I run app, Postgres, and Redis locally, so allocate non-conflicting ports and write the resulting mapping. Copy env files but do not install dependencies until I approve the command. Show the exact script command and any Docker Compose override I may need.
Damit bekommt der Skill genug Informationen, um die Branch-Strategie zu wählen, Port-Kollisionen zu vermeiden, vorsichtig mit .env*-Dateien umzugehen und Planung sauber von Ausführung zu trennen.
FAQ zum git-worktree-manager Skill
Ist git-worktree-manager nur für AI Agents gedacht?
Nein. Der Skill ist für Multi-Agent-Arbeit optimiert, aber die Skripte und Konventionen sind auch für menschliche Entwickler:innen nützlich. Der Hauptvorteil ist Wiederholbarkeit: Jeder worktree bekommt einen vorhersehbaren Branch, ein Verzeichnis, Ports, kopierte env-Dateien und eine Cleanup-Prüfung, statt dass alles aus einer improvisierten Shell-History entsteht.
Worin unterscheidet sich das von einfachem git worktree?
Ein einfaches git worktree add erstellt ein weiteres Checkout. Lokale App-Konflikte löst es nicht. git-worktree-manager ergänzt den umliegenden Workflow: Port-Blöcke, .worktree-ports.json, Kopieren von Umgebungsdateien, optionale Dependency-Installation, Hinweise zur Docker Compose-Isolation und Cleanup-Prüfungen für veraltete oder gemergte Branches.
Können Einsteiger:innen das sicher verwenden?
Ja, wenn sie den Skill als geführten Workflow behandeln und nicht als blind auszuführenden Befehlsstarter. Einsteiger:innen sollten zunächst Listen- und Prüfoperationen ausführen, --format text verwenden, automatisches Entfernen vermeiden und generierte Befehle vor der Ausführung prüfen. Das Cleanup-Skript prüft auf dirty worktrees, trotzdem solltest du verstehen, welche Branches sicher gelöscht werden können.
Wann sollte ich diesen Skill nicht verwenden?
Verwende ihn nicht unverändert, wenn dein Repository ungewöhnliches Environment-Handling hat, Secrets niemals kopiert werden dürfen, die Dependency-Installation nicht standardisiert ist oder Service-Ports durch eine interne Plattform verwaltet werden. In solchen Fällen solltest du den git-worktree-manager guide als Ausgangsmuster nutzen und Skripte oder Prompts vor der Einführung anpassen.
So verbesserst du den git-worktree-manager Skill
Gib git-worktree-manager mehr Repository-Kontext
Bessere Eingaben führen zu sichereren worktree-Plänen. Gib Folgendes an:
- absoluter Repository-Pfad
- Ziel-Branch und Base-Branch
- gewünschter Verzeichnisname für den worktree
- erwarteter Package Manager oder erwartete Lockfiles
- Services, die Ports benötigen
- ob
.env*-Dateien kopiert werden dürfen - ob Dependency-Installation erlaubt ist
- Altersgrenze für Cleanup und Base-Branch für Merge-Prüfungen
Das reduziert Raten und verhindert, dass der Agent Defaults annimmt, die nicht zu deiner App passen.
Port- und Docker Compose-Konventionen anpassen
Die Referenzstrategie verwendet Standard-Basiswerte wie App 3000, Postgres 5432, Redis 6379, mit einem Abstand von 10 pro worktree. Wenn dein Stack mehr Services hat, reserviere einen größeren zusammenhängenden Block. Wenn du lokale Infrastruktur außerhalb der worktrees betreibst, verschiebe die Basis-Ports, um globale Kollisionen zu vermeiden.
Für Docker Compose solltest du Overrides pro worktree, über .env gesteuerte Ports und eindeutige Projektnamen bevorzugen, zum Beispiel:
docker compose -p myapp_wt_auth up -d
So vermeidest du Kollisionen bei Containern, Netzwerken, Volumes und Datenbanken zwischen Branches.
Häufige Fehlerquellen im Blick behalten
Die häufigsten Probleme sind kopierte Secrets, wiederverwendete Standard-Datenbankports, gemeinsam genutzte Docker-Volumes trotz inkompatibler Migrationen, Dependency-Installationen in der falschen Runtime und das Löschen eines worktrees mit noch nicht committeten Änderungen. Bitte den Agenten nach jedem Lauf, dirty status, kopierte env-Dateien, gewählte Ports und Installationsaktionen auszugeben.
Beginne beim Cleanup mit einer reinen Review-Ausgabe. Aktiviere das Entfernen erst, nachdem bestätigt ist, dass ein worktree veraltet, clean und in den erwarteten Base-Branch gemergt ist.
Nach der ersten Ausgabe gezielt iterieren
Bitte nach dem ersten Plan oder Befehl um eine fokussierte Überarbeitung, statt von vorn zu beginnen:
Revise the
git-worktree-managercommand to skip dependency installation, use base branchdevelop, reserve ports for app, Postgres, Redis, and Mailhog, and output JSON for automation.
So bleibt der Skill an den realen Einschränkungen des Repositorys ausgerichtet und verbessert zugleich Sicherheit und Reproduzierbarkeit.