using-git-worktrees

Vue d’ensemble de la compétence using-git-worktrees

Ce que fait la compétence using-git-worktrees

La compétence using-git-worktrees aide un agent à créer un worktree Git séparé pour un nouveau travail, au lieu de réutiliser votre checkout courant. Son vrai rôle ne se limite pas à « exécuter git worktree add » : elle sert aussi à choisir un répertoire pertinent, à vérifier que les dossiers de worktree locaux sont bien ignorés en toute sécurité, et à éviter de polluer l’espace de travail principal.

À qui s’adresse son installation

Cette compétence convient particulièrement aux personnes qui :

• démarrent régulièrement de nouvelles fonctionnalités tout en laissant intactes les modifications en cours
• révisent ou implémentent plusieurs branches en parallèle
• veulent des workflows de développement pilotés par IA plus sûrs, avec moins de risques liés aux changements de branche
• ont besoin d’une méthode reproductible pour créer des espaces de travail isolés d’un projet à l’autre

Si vous demandez souvent à un assistant de « démarrer ça dans une branche séparée » ou de « travailler sans toucher à mon arbre courant », using-git-worktrees est un très bon choix.

Le besoin concret auquel elle répond

Les utilisateurs recherchent un résultat simple : commencer une implémentation dans un espace de travail isolé, avec un minimum d’erreurs de configuration. La compétence using-git-worktrees est utile parce qu’elle ajoute un processus de décision avant la création :

• privilégier un répertoire de worktrees du projet s’il existe déjà
• respecter la préférence documentée dans CLAUDE.md si elle existe
• demander à l’utilisateur quand aucun choix sûr par défaut n’existe
• vérifier le comportement d’ignorance avant de créer des worktrees locaux au projet

C’est ce qui la rend plus fiable qu’un prompt générique qui passe directement aux commandes shell.

Ce qui la différencie d’un prompt classique

Un prompt classique peut connaître le principe des Git worktrees, tout en passant à côté de détails de configuration propres au dépôt. Cette compétence fournit à l’agent un ordre d’opérations clair et des vérifications de sécurité, notamment sur l’emplacement des répertoires et la gestion de .gitignore. C’est le principal différenciateur de using-git-worktrees for Git Workflows : moins d’improvisation au moment du setup, pas plus de théorie Git.

Quand cette compétence est peu adaptée

Évitez using-git-worktrees si :

• vous travaillez toujours dans une seule branche et un seul répertoire
• votre environnement interdit les répertoires de travail supplémentaires
• vous avez seulement besoin de changer rapidement de branche, pas d’une exécution isolée
• votre équipe dispose déjà d’un script wrapper figé qui remplace entièrement cette logique de décision

Dans ces cas-là, une simple commande shell ou votre workflow interne sera probablement plus rapide.

Comment utiliser la compétence using-git-worktrees

Contexte d’installation de using-git-worktrees

Installez-la depuis la collection de compétences obra/superpowers :

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

Après l’installation, utilisez-la au moment de démarrer un travail qui ne doit pas réutiliser le checkout actuel.

Comment les utilisateurs déclenchent réellement la compétence

Le dépôt indique explicitement que l’agent doit annoncer l’utilisation de la compétence au début. En pratique, votre demande doit rendre l’exigence d’isolation évidente, par exemple :

• « Utilise using-git-worktrees et prépare un espace de travail isolé pour cette fonctionnalité. »
• « Avant d’implémenter, crée un worktree pour la branche feature/auth-refresh. »
• « Utilise la compétence using-git-worktrees pour que mes modifications actuelles restent intactes. »

Cela augmente les chances que l’agent suive bien la compétence au lieu d’improviser.

Quelles entrées fournir à la compétence

Pour obtenir de bons résultats, fournissez :

• le nom de la branche cible
• s’il s’agit d’une nouvelle branche ou d’une branche existante
• si vous préférez un stockage des worktrees local au projet ou global
• toute contrainte propre au dépôt, par exemple « doit rester sous la racine du projet »

Entrée minimale utile :

• nom de branche ou de tâche
• autorisation de créer un worktree

Entrée plus complète :

• nom de la branche
• politique de répertoire souhaitée
• présence ou non de modifications non commit sur le checkout actuel
• ce qui doit se passer après le setup, par exemple « puis commence l’implémentation »

La logique intégrée de choix du répertoire

La using-git-worktrees skill est surtout utile pour son workflow de sélection du répertoire. Elle suit cet ordre de priorité :

1. utiliser .worktrees s’il existe déjà
2. sinon utiliser worktrees s’il existe
3. sinon inspecter CLAUDE.md pour y trouver une préférence documentée
4. sinon demander à l’utilisateur de choisir entre :
   • .worktrees/
   • ~/.config/superpowers/worktrees/<project-name>/

C’est important, car la dispersion des worktrees devient vite un vrai problème de maintenance si chaque session invente son propre emplacement.

Vérifications de sécurité avant une création locale au projet

Point clé pour l’adoption : si le worktree doit être créé à l’intérieur du dépôt, la compétence impose de vérifier que le répertoire est bien ignoré avant de le créer. Cela évite de versionner par erreur des dossiers de worktree ou d’encombrer la sortie de statut.

C’est un avantage réel par rapport à un usage ad hoc. Si votre équipe veut des worktrees locaux au projet, assurez-vous que .worktrees/ ou worktrees/ est ignoré par Git avant de vous reposer sur ce workflow.

Exemples de prompts efficaces pour utiliser using-git-worktrees

Prompt faible :

• « Commence à travailler sur le nettoyage OAuth. »

Prompt plus solide :

• « Utilise using-git-worktrees pour créer un espace de travail isolé pour la nouvelle branche feature/oauth-cleanup. Privilégie .worktrees/ si c’est sûr et ignoré. Après le setup, commence l’implémentation sans toucher à mon checkout actuel. »

Pourquoi c’est mieux :

• la compétence est nommée
• une branche cible est donnée
• la préférence de répertoire est indiquée
• l’agent sait quoi faire ensuite

Workflow recommandé après la création

Une séquence pratique pour l’usage de using-git-worktrees :

1. demander à l’agent d’utiliser la compétence
2. confirmer l’emplacement du worktree et le nom de la branche
3. faire basculer le travail de l’agent dans le nouvel espace
4. ensuite seulement lancer les modifications, les tests ou la planification d’implémentation

Cette séquence est particulièrement utile si votre checkout courant contient déjà des modifications non commit.

Fichiers à lire en premier dans le dépôt

Il n’y a ici qu’un seul fichier source vraiment important : SKILL.md.

Lisez-le pour :

• l’ordre de priorité exact des répertoires
• le prompt utilisateur attendu lorsqu’aucune préférence n’existe
• l’exigence de vérification des règles d’ignorance
• la formulation d’activation qui indique à l’agent d’annoncer l’usage de la compétence

Cette compétence est légère : la vraie question avant adoption est donc de savoir si cette logique correspond au workflow Git de votre équipe.

Contraintes pratiques à connaître avant de s’y fier

La compétence est volontairement limitée. Elle ne semble pas fournir :

• de scripts wrapper
• d’outils d’automatisation
• d’application stricte des conventions de nommage de branches
• de routines de nettoyage des worktrees obsolètes
• de solutions de repli spécifiques à une plateforme

Autrement dit, using-git-worktrees install vous apporte une logique de décision, pas un système complet de gestion des worktrees. Si vous avez besoin d’automatiser tout le cycle de vie, associez-la à vos propres outils shell.

FAQ sur la compétence using-git-worktrees

using-git-worktrees est-elle adaptée aux débutants ?

Oui, si le débutant comprend déjà les bases des branches et veut un workflow plus sûr de type « ne touche pas à mon espace de travail actuel ». Ce n’est pas un tutoriel Git ; c’est une compétence de configuration structurée. Un vrai débutant aura peut-être encore besoin d’aide pour comprendre ce qu’est un worktree et en quoi il diffère d’un clone.

Quel problème résout-elle mieux qu’un prompt ordinaire ?

Les prompts ordinaires sautent souvent la partie la plus délicate : où placer le worktree et comment vérifier qu’un répertoire local au projet est bien ignoré. Le using-git-worktrees guide encodé dans la compétence réduit ces erreurs de configuration et rend le comportement de l’agent plus cohérent.

Faut-il des worktrees locaux au projet pour l’utiliser ?

Non. La compétence peut orienter vers un emplacement global lorsqu’aucun répertoire local n’existe et qu’aucune préférence n’est documentée dans le dépôt. Elle reste donc utile même si vous ne voulez pas de dossiers supplémentaires dans le repository.

Peut-on utiliser using-git-worktrees avec des branches existantes ?

Oui. Le workflow reste pertinent lorsqu’il s’agit de checkout une branche existante dans un espace de travail séparé. La valeur principale, c’est l’isolation, pas uniquement la création de branche.

Quand ne faut-il pas utiliser using-git-worktrees ?

Ne l’utilisez pas si :

• vous faites seulement une toute petite modification dans votre branche actuelle
• votre équipe interdit les emplacements de worktree non gérés
• vous disposez déjà d’un outillage interne déterministe qui gère l’emplacement et les règles d’ignorance
• votre dépôt impose des contraintes Git inhabituelles que la compétence ne connaît pas

Est-ce que cela remplace les connaissances Git ?

Non. La using-git-worktrees skill améliore la discipline d’invocation et de configuration, mais vous avez toujours besoin d’un minimum de jugement Git pour le nommage des branches, le rebase, le nettoyage et la stratégie de fusion.

Comment améliorer la compétence using-git-worktrees

Indiquer explicitement la branche et la politique de répertoire

Le plus gros gain de qualité consiste à indiquer à l’agent à la fois la branche cible et la politique de répertoire souhaitée. Exemple :

« Utilise using-git-worktrees pour la branche fix/cache-invalidation. Si .worktrees/ existe et est ignoré, utilise-le ; sinon, demande avant de passer à un emplacement global. »

Cela supprime la source d’ambiguïté la plus fréquente.

Documenter les préférences dans CLAUDE.md

Comme la compétence consulte CLAUDE.md, vous pouvez améliorer les résultats futurs en y documentant :

• le répertoire de worktrees préféré
• si les worktrees locaux au projet sont autorisés
• les conventions de nommage des branches ou des dossiers

Vous transformez ainsi des clarifications répétées côté utilisateur en politique définie au niveau du dépôt.

Préconfigurer les règles d’ignorance pour les répertoires locaux

Si votre équipe veut des répertoires .worktrees/ ou worktrees/ dans le projet, ajoutez la règle d’ignorance à l’avance. Cela fluidifie le parcours using-git-worktrees for Git Workflows, car la vérification de sécurité passe proprement au lieu de déclencher une discussion en plein milieu de la tâche.

Surveiller les modes d’échec courants

Les principaux modes d’échec sont prévisibles :

• l’agent crée un worktree dans un emplacement non approuvé
• les dossiers de worktree locaux ne sont pas ignorés
• le nom de branche est mal déduit à partir d’une demande de fonctionnalité trop vague
• l’implémentation commence dans le checkout d’origine avant que l’isolation soit terminée

La plupart de ces problèmes viennent de prompts incomplets, pas de la compétence elle-même.

Demander une confirmation avant le début du code

Un prompt d’amélioration simple :

• « Utilise using-git-worktrees, puis indique-moi le chemin final et la branche avant de modifier quoi que ce soit. »

Cela permet d’attraper les erreurs tôt, et c’est particulièrement utile dans les dépôts avec plusieurs dossiers imbriqués ou des règles inhabituelles.

Itérer après la première exécution

Si le premier résultat est acceptable sans être idéal, affinez votre façon de travailler plutôt que de tout réécrire :

• fixez clairement votre emplacement de worktree préféré
• ajoutez une note dans CLAUDE.md
• standardisez le nommage des branches dans les prompts
• exigez explicitement une confirmation avant toute modification

Avec le temps, l’usage de using-git-worktrees devient ainsi plus prévisible et les frictions répétées au moment du setup diminuent.