git-worktree

Git Worktree

Kein Worktree entsteht, ohne dass der Benutzer weiß, wo er liegt, von wo er ausgeht und wie er wieder verlassen wird. Kein Worktree wird gelöscht, ohne dass der Benutzer darum bittet.

Diese Skill hat Vorrang vor anderen Skills, die Worktrees erstellen (z.B. superpowers:using-git-worktrees) in drei Punkten: Pfad, Name und Freigabe. Der restliche Ablauf der anderen Skill bleibt gültig.

Tools pro Agent

Aktion	Claude Code	Codex
Erstellen	git worktree add + EnterWorktree(path: …) zum Verschieben der Sitzung	git worktree add und mit git -C/workdir im Worktree arbeiten
Isolierter Subagent	Agent mit isolation: "worktree" (erstellt in .claude/worktrees/)	nicht anwendbar
Verlassen	ExitWorktree(action: "keep")	zurück zum ursprünglichen Verzeichnis
Bericht	pwsh -NoProfile -File "<Ordner dieser Skill>/scripts/worktrees-report.ps1"	gleich

<Ordner dieser Skill> ist das Verzeichnis, in dem diese SKILL.md liegt. Das Skript benötigt PowerShell 7+ (pwsh).

1. Vor dem Erstellen

1. Prüfen, ob Sie sich bereits in einem Worktree befinden (git rev-parse --git-dir unterscheidet sich von git rev-parse --git-common-dir, außerhalb eines Submoduls). Falls ja, keinen weiteren ohne Aufforderung des Benutzers erstellen.
2. Führen Sie den Bericht in den beteiligten Repositories aus und speichern Sie das Ergebnis für Schritt 4:

   pwsh -NoProfile -File "<Ordner dieser Skill>/scripts/worktrees-report.ps1" -Path "<repo1>;<repo2>"
   

3. Erstellen Sie den Plan mit den unten stehenden Standards und geben Sie einen Block pro Worktree aus:

   Worktree-Plan
   - Repository:        C:\repos\shop
   - Basis-Branch:      origin/main @ 3f2a9c1 (git fetch soeben ausgeführt)
   - Neuer Branch:      claude/feat-login-google
   - Name:              feat-login-google
   - Absoluter Pfad:    C:\repos\shop\.worktrees\feat-login-google
   - Relativer Pfad:    .worktrees\feat-login-google
   - Ausführung:        git -C "C:\repos\shop" worktree add "C:\repos\shop\.worktrees\feat-login-google" -b claude/feat-login-google origin/main
   - Entfernung:        git -C "C:\repos\shop" worktree remove "C:\repos\shop\.worktrees\feat-login-google"
                        git -C "C:\repos\shop" branch -d claude/feat-login-google
   

   Falls das Repository Submodule enthält (.gitmodules), weisen Sie im Plan darauf hin, dass die Entfernung --force benötigt und warum.
4. Zeigen Sie direkt darunter die Tabelle des Berichts mit den bereits geöffneten Worktrees in diesen Repositories an (Worktree, Größe, Branch, Was ich verliere). Falls es keine gibt, sagen Sie das in einer Zeile.
5. Warten Sie auf das explizite OK des Benutzers. Erst dann erstellen. Bei Claude Code fordert der Plugin-Hook eine zusätzliche Bestätigung beim Befehl. Bei Codex sorgt die Regel codex/rules/git-worktree.rules für dasselbe bei git worktree add.

Für mehrere parallele Subagenten präsentieren Sie einen einzigen Plan mit allen Worktrees und holen ein einziges OK ein.

Standards

• Pfad: <Repository-Wurzel>/.worktrees/<Name> in beiden Agenten. Ausnahme: der Claude-Code-Subagent mit isolation: "worktree" erstellt immer in .claude/worktrees/; geben Sie diesen Pfad im Plan an.
• Ordner vor dem Commit ignorieren: Vor dem Erstellen git -C <repo> check-ignore -q .worktrees/x ausführen. Falls der Ordner nicht ignoriert wird, fügen Sie .worktrees/ zur Datei info/exclude des Repositories hinzu (Pfad via git -C <repo> rev-parse --git-path info/exclude). Diese Datei ist lokal und erzeugt keinen Commit. Informieren Sie, dass Sie dies getan haben.
• Name: <typ>-<kurzbeschreibung> in kebab-case, maximal 40 Zeichen. Beispiele: feat-login-google, fix-timeout-pagamento.
• Neuer Branch: <agent>/<name>, also claude/feat-login-google oder codex/feat-login-google. Falls das Repository eine eigene Branch-Konvention hat (Hook, CONTRIBUTING, Historie), folgen Sie dieser und geben Sie an, welche es ist.
• Basis: standardmäßig der Branch, auf dem der Benutzer im Haupt-Checkout ist. Verwenden Sie origin/<standard-branch>, wenn die Aufgabe unabhängig davon ist. Führen Sie vorher git fetch aus und zeigen Sie den kurzen Hash der Basis.

2. Worktree-Bericht

Verwenden, wenn der Benutzer Worktrees auflisten oder bereinigen möchte, sowie in Schritt 1.2 oben.

pwsh -NoProfile -File "<Ordner dieser Skill>/scripts/worktrees-report.ps1" [-Path "<wurzel oder repo>;..."] [-Json] [-SkipSize] [-Depth 6]

• Ohne -Path verwendet das Skript die Variable GIT_WORKTREE_ROOTS oder, falls nicht gesetzt, das aktuelle Verzeichnis. Falls die Anweisungen des Benutzers (CLAUDE.md, AGENTS.md) einen Repository-Wurzelordner definieren, übergeben Sie diesen Ordner.
• Das Skript ist schreibgeschützt. Es findet Repositories, Submodule und freistehende Worktrees außerhalb des Repository-Ordners.
• Verwenden Sie -SkipSize, wenn der Benutzer Geschwindigkeit wünscht. Verwenden Sie -Json, wenn Sie die Details benötigen (Commits voraus/zurück, Remote-Status, Merge, Datum des letzten Commits, Urteil und Entfernungskommandos).

Zeigen Sie die Tabelle, die das Skript ausgibt, mit genau diesen vier Spalten und in dieser Reihenfolge:

Spalte	Inhalt
Worktree	Absoluter Pfad
Größe	Speicherplatz auf der Festplatte
Branch	Branch des Worktrees oder (detached @ <hash>)
Was ich verliere	Nichts oder die Liste dessen, was beim Löschen verschwindet: uncommittete Dateien, nur dort existierende Commits, von Git ignorierte Dateien (z.B. .env). Build-Ordner (node_modules, bin, obj …) zählen nicht

Fügen Sie keine Spalten hinzu. Details stehen unterhalb der Tabelle, nur wenn sie bei der Entscheidung helfen.

Was als Verlust zählt:

• Geänderte oder neue Dateien ohne Commit.
• Commits, die weder auf einem Remote, noch im aktuellen Branch, noch im Standard-Branch sind.
• Ignorierte Dateien, die keine Build-Artefakte sind.
• In initialisierten Submodulen: uncommittete Dateien und Commits, die nur dort existieren.
• Ein gesperrter Worktree (git worktree lock) erscheint mit (gesperrt…) und wird ohne Bestätigung nicht gelöscht.
• Falls der Ordner nicht mehr existiert, sagt die Spalte Nichts (der Ordner existiert nicht mehr…). Behebung mit git worktree prune.
• Einschränkung: Squash- oder Rebase-Merges werden nicht erkannt, daher erscheinen diese Commits als Verlust. Sagt der Benutzer, der PR sei bereits gemerged, prüfen Sie auf dem Remote.

Schließen Sie den Bericht mit dem Speicherplatz ab, der freigegeben würde, wenn diejenigen gelöscht werden, die nichts verlieren.

Entfernungskommandos

Wenn der Benutzer um Löschung bittet oder nach dem Befehl fragt, verwenden Sie das Feld ComandosRemocao aus -Json. Kopieren Sie die Befehle exakt, in der Reihenfolge und in einem einzigen Block. Schreiben Sie die Befehle nicht aus dem Kopf. Das Feld löst bereits drei Fallstricke:

1. Ignorierte Dateien: Falls ignorierte Dateien verloren gehen (z.B. .env, .superpowers/), kopieren die ersten Befehle sie nach ~/worktree-backup/<repo>/<worktree>. Das Kopieren muss vor dem Entfernen erfolgen: nach dem Entfernen gibt es nichts mehr zu kopieren.
2. Submodule: Falls der Worktree initialisierte Submodule enthält, erfolgt die Entfernung mit --force, weil git git worktree remove ohne diesen ablehnt. Bevor Sie diesen Befehl ausgeben, bestätigen Sie in der Spalte „Was ich verliere”, dass die Submodule nichts verlieren oder der Benutzer den Verlust akzeptiert hat.
3. Branch: Zuletzt löscht git branch -d den Branch, was nur funktioniert, wenn er bereits integriert ist.

Wenn Sie die Befehle selbst ausführen, führen Sie einen Befehl nach dem anderen aus und stoppen Sie beim ersten Fehler.

3. Nach Abschluss der Aufgabe

• Falls die Arbeit des Worktrees bereits integriert ist (gemerged oder auf den Remote gepusht), schlagen Sie die Entfernung mit den fertigen Kommandos vor.
• Falls nicht, sagen Sie, was fehlt: Commit, Push, PR.
• Bei Claude Code verlassen Sie mit ExitWorktree(action: "keep") und entfernen nur über git nach dem OK. ExitWorktree(action: "remove") funktioniert nur für Worktrees, die EnterWorktree selbst in der Sitzung erstellt hat.

Unveränderliche Regeln

• Niemals einen Worktree oder Branch ohne Aufforderung des Benutzers löschen. Löschen Sie einen nach dem anderen und führen Sie am Ende erneut den Bericht aus.
• Niemals git branch -D oder ExitWorktree(discard_changes: true) ohne explizite Bestätigung für diesen Worktree verwenden. git worktree remove --force kommt nur zum Einsatz, wenn der Worktree Submodule hat (siehe „Entfernungskommandos”) und der Benutzer gesehen hat, was verloren geht.
• Niemals einen Worktree erstellen, ohne den Plan präsentiert und das OK erhalten zu haben.