git-worktree

Git Worktree

Aucun worktree ne naît sans que l'utilisateur sache où il se trouve, d'où il part et comment en sortir. Aucun worktree n'est supprimé sans que l'utilisateur le demande.

Cette compétence a priorité sur les autres compétences qui créent un worktree (ex. : superpowers:using-git-worktrees) sur trois points : emplacement, nom et approbation. Le reste du flux de l'autre compétence reste valable.

Outils par agent

Action	Claude Code	Codex
Créer	git worktree add + EnterWorktree(path: ...) pour déplacer la session	git worktree add et travailler avec git -C/workdir dans le worktree
Sous-agent isolé	Agent avec isolation: "worktree" (crée dans .claude/worktrees/)	non applicable
Sortir	ExitWorktree(action: "keep")	revenir au répertoire d'origine
Rapport	pwsh -NoProfile -File "<dossier de cette compétence>/scripts/worktrees-report.ps1"	idem

<dossier de cette compétence> est le répertoire où se trouve ce SKILL.md. Le script nécessite PowerShell 7+ (pwsh).

1. Avant de créer

1. Vérifiez si vous êtes déjà dans un worktree (git rev-parse --git-dir différent de git rev-parse --git-common-dir, hors sous-module). Si c'est le cas, n'en créez pas d'autre sans que l'utilisateur le demande.
2. Lancez le rapport sur les dépôts concernés et conservez le résultat pour l'étape 4 :

   pwsh -NoProfile -File "<dossier de cette compétence>/scripts/worktrees-report.ps1" -Path "<repo1>;<repo2>"
   

3. Élaborez le plan avec les valeurs par défaut ci-dessous et présentez un bloc par worktree :

   Plan du worktree
   - Dépôt :             C:\repos\loja
   - Branche de base :   origin/main @ 3f2a9c1 (git fetch effectué maintenant)
   - Nouvelle branche :  claude/feat-login-google
   - Nom :               feat-login-google
   - Emplacement absolu : C:\repos\loja\.worktrees\feat-login-google
   - Emplacement relatif : .worktrees\feat-login-google
   - Commande :          git -C "C:\repos\loja" worktree add "C:\repos\loja\.worktrees\feat-login-google" -b claude/feat-login-google origin/main
   - Suppression :       git -C "C:\repos\loja" worktree remove "C:\repos\loja\.worktrees\feat-login-google"
                         git -C "C:\repos\loja" branch -d claude/feat-login-google
   

   Si le dépôt a des sous-modules (.gitmodules), prévenez dans le plan que la suppression nécessitera --force et expliquez pourquoi.
4. Juste en dessous, affichez le tableau du rapport avec les worktrees déjà ouverts dans ces dépôts (Worktree, Taille, Branche, Ce que je perds). S'il n'y en a aucun, dites-le en une ligne.
5. Attendez l'OK explicite de l'utilisateur. Ce n'est qu'après que vous créez. Dans Claude Code, le hook du plugin demande une confirmation supplémentaire au moment de la commande. Dans Codex, la règle codex/rules/git-worktree.rules fait de même pour git worktree add.

Pour plusieurs sous-agents en parallèle, présentez un plan unique avec tous les worktrees et demandez un seul OK.

Valeurs par défaut

• Emplacement : <racine du dépôt>/.worktrees/<nom>, pour les deux agents. L'exception est le sous-agent de Claude Code avec isolation: "worktree", qui crée toujours dans .claude/worktrees/ ; dans ce cas, indiquez ce chemin dans le plan.
• Ignorer le dossier sans commit : avant de créer, lancez git -C <repo> check-ignore -q .worktrees/x. Si le dossier n'est pas ignoré, ajoutez .worktrees/ au fichier info/exclude du dépôt (chemin dans git -C <repo> rev-parse --git-path info/exclude). Ce fichier est local et ne génère pas de commit. Prévenez que vous l'avez fait.
• Nom : <type>-<description-courte>, en kebab-case, avec au maximum 40 caractères. Exemples : feat-login-google, fix-timeout-pagamento.
• Nouvelle branche : <agent>/<nom>, soit claude/feat-login-google ou codex/feat-login-google. Si le dépôt a sa propre convention de branche (hook, CONTRIBUTING, historique), suivez celle du dépôt et dites laquelle.
• Base : par défaut, la branche sur laquelle l'utilisateur se trouve dans le checkout principal. Utilisez origin/<branche-par-defaut> si la tâche en est indépendante. Lancez git fetch avant et montrez le hash court de la base.

2. Rapport de worktrees

Utilisez lorsque l'utilisateur demande de lister ou nettoyer les worktrees et à l'étape 1.2 ci-dessus.

pwsh -NoProfile -File "<dossier de cette compétence>/scripts/worktrees-report.ps1" [-Path "<racine ou dépôt>;..."] [-Json] [-SkipSize] [-Depth 6]

• Sans -Path, le script utilise la variable GIT_WORKTREE_ROOTS ou, à défaut, le répertoire courant. Si les instructions de l'utilisateur (CLAUDE.md, AGENTS.md) définissent un dossier racine des dépôts, passez ce dossier.
• Le script est en lecture seule. Il trouve les dépôts, sous-modules et worktrees détachés en dehors du dossier du dépôt.
• Utilisez -SkipSize si l'utilisateur souhaite de la rapidité. Utilisez -Json lorsque vous avez besoin des détails (commits en avance/en retard, statut sur le remote, merge, date du dernier commit, verdict et commandes de suppression).

Affichez le tableau que le script imprime, avec exactement ces quatre colonnes et dans cet ordre :

Colonne	Contenu
Worktree	Chemin absolu
Taille	Espace disque
Branche	Branche du worktree, ou (detached @ <hash>)
Ce que je perds	Rien, ou la liste de ce qui disparaît en supprimant : fichiers non commités, commits qui n'existent que là, fichiers ignorés par git (ex. : .env). Les dossiers de build (node_modules, bin, obj...) ne comptent pas

N'ajoutez pas de colonnes. Les détails vont en dessous du tableau, seulement s'ils aident à décider.

Ce qui compte comme perte :

• Fichiers modifiés ou nouveaux sans commit.
• Commits qui ne sont sur aucun remote, ni sur la branche courante, ni sur la branche par défaut.
• Fichiers ignorés qui ne sont pas de build.
• Dans les sous-modules initialisés : fichiers non commités et commits qui n'existent que dedans.
• Un worktree verrouillé (git worktree lock) apparaît avec (verrouillé...) et n'est pas supprimé sans confirmation.
• Si le dossier n'existe déjà plus, la colonne dit Rien (le dossier n'existe déjà plus...). Résolvez avec git worktree prune.
• Limitation : les merges par squash ou rebase ne sont pas détectés, donc ces commits apparaissent comme perdus. Si l'utilisateur dit que la PR a déjà été mergée, vérifiez sur le remote.

Fermez le rapport avec l'espace qui serait libéré en supprimant ceux qui ne perdent rien.

Commandes de suppression

Lorsque l'utilisateur demande de supprimer, ou demande la commande, utilisez le champ ComandosRemocao du -Json. Copiez les commandes exactement, dans l'ordre et en un seul bloc. N'écrivez pas les commandes de mémoire. Le champ gère déjà trois pièges :

1. Fichiers ignorés : s'il y a des fichiers ignorés qui se perdent (ex. : .env, .superpowers/), les premières commandes les copient vers ~/worktree-backup/<repo>/<worktree>. La copie doit venir avant la suppression : après avoir supprimé, il n'y a plus rien à copier.
2. Sous-modules : si le worktree a des sous-modules initialisés, la suppression vient avec --force, car git refuse git worktree remove sans cela. Avant de donner cette commande, confirmez dans la colonne "Ce que je perds" que les sous-modules ne perdent rien, ou que l'utilisateur a accepté la perte.
3. Branche : enfin, git branch -d supprime la branche, qui ne part que si elle est déjà intégrée.

Si vous exécutez vous-même, lancez une commande à la fois et arrêtez-vous à la première erreur.

3. En finissant la tâche

• Si le travail du worktree a déjà été intégré (mergé ou poussé sur le remote), proposez la suppression avec les commandes prêtes.
• Sinon, dites ce qui manque : commit, push, PR.
• Dans Claude Code, sortez avec ExitWorktree(action: "keep") et ne supprimez via git qu'après l'OK. ExitWorktree(action: "remove") fonctionne seulement pour les worktrees que EnterWorktree a créés dans la session.

Règles qui ne changent pas

• Ne supprimez jamais un worktree ou une branche sans que l'utilisateur le demande. Supprimez un à la fois et relancez le rapport à la fin.
• N'utilisez jamais git branch -D ou ExitWorktree(discard_changes: true) sans confirmation explicite pour ce worktree. git worktree remove --force n'intervient que lorsque le worktree a des sous-modules (voir "Commandes de suppression") et que l'utilisateur a déjà vu ce qui se perd.
• Ne créez jamais un worktree sans avoir présenté le plan et reçu l'OK.