git-worktree-manager

Présentation de la skill git-worktree-manager

Ce que fait git-worktree-manager

git-worktree-manager est une skill d’ingénierie conçue pour gérer plusieurs Git worktrees locaux sans conflits de branches, de ports, d’environnements ni de nettoyage. Elle associe des recommandations opérationnelles à des scripts d’aide en Python qui créent des worktrees prêts à l’emploi, attribuent des ports déterministes, copient les fichiers d’environnement locaux, installent éventuellement les dépendances et passent en revue les worktrees obsolètes avant suppression.

Utilisez cette skill lorsque les commandes git worktree classiques ne suffisent plus parce que chaque branche doit se comporter comme une application exécutable distincte.

Idéal pour les workflows Git en parallèle

Le profil le plus adapté est un développeur, un tech lead ou un opérateur d’agents de code qui garde au moins deux branches ouvertes en même temps : développement de fonctionnalités, hotfixes, revue de PR, tests de migration ou implémentation multi-agent. git-worktree-manager for Git Workflows est particulièrement utile lorsque chaque agent ou session de terminal doit posséder sa propre branche et son runtime isolé, au lieu de partager un unique checkout.

La skill a moins d’intérêt si vous ne changez de branche qu’occasionnellement, si vous ne lancez pas de services locaux ou si vous disposez déjà d’un wrapper interne mature autour des worktrees.

Points différenciants à vérifier avant l’installation

La valeur pratique ne se limite pas à « créer un worktree ». La skill ajoute des conventions reproductibles autour de :

• la création de branches et le nommage déterministe des worktrees
• l’allocation de ports non chevauchants pour l’application, la base de données et Redis
• la synchronisation de .env, .env.local, .env.development et .envrc
• la détection de l’installation des dépendances à partir des lockfiles courants
• les contrôles de nettoyage pour les worktrees obsolètes, modifiés ou associés à des branches déjà mergées
• les modèles Docker Compose pour isoler les services par worktree

Cela rend la git-worktree-manager skill plus opérationnelle qu’un simple prompt générique sur les Git worktrees.

Comment utiliser la skill git-worktree-manager

Options d’installation de git-worktree-manager

Pour une configuration de skills de type Claude, installez-la depuis le dépôt avec votre gestionnaire de skills si disponible :

npx skills add alirezarezvani/claude-skills --skill git-worktree-manager

Pour une installation manuelle, copiez le répertoire de la skill depuis :

engineering/skills/git-worktree-manager

vers votre dossier local de skills, par exemple ~/.claude/skills/git-worktree-manager, ~/.codex/skills/git-worktree-manager ou un autre répertoire compatible avec les skills de votre agent. Après l’installation, vérifiez que les fichiers suivants sont présents : SKILL.md, README.md, scripts/worktree_manager.py, scripts/worktree_cleanup.py, ainsi que les deux fichiers sous references/.

Fichiers à lire en premier

Pour une prise en main rapide, lisez les fichiers dans cet ordre :

1. README.md pour la forme des commandes et la liste des outils.
2. SKILL.md pour le workflow prévu et les indications sur les cas d’usage.
3. references/port-allocation-strategy.md avant de modifier les ports des services.
4. references/docker-compose-patterns.md si votre application utilise Compose.
5. scripts/worktree_manager.py et scripts/worktree_cleanup.py avant de faire confiance à l’automatisation dans un dépôt de production.

C’est important, car les scripts modifient de vrais checkouts, copient des fichiers d’environnement et peuvent installer des dépendances. Passez les valeurs par défaut en revue avant de les exécuter sur un grand monorepo ou sur un dépôt contenant une configuration locale sensible.

Utilisation concrète de git-worktree-manager

Un flux typique de création et de préparation ressemble à ceci :

python scripts/worktree_manager.py \
  --repo . \
  --branch feature/api-hardening \
  --name wt-api-hardening \
  --base-branch main \
  --install-deps \
  --format text

Un flux de revue avant nettoyage ressemble à ceci :

python scripts/worktree_cleanup.py \
  --repo . \
  --stale-days 14 \
  --format text

Les deux outils prennent en charge une entrée JSON via --input <json-file> ou stdin, ce qui est utile pour l’automatisation. Demandez d’abord à l’agent de produire un plan de commande, puis n’exécutez le script qu’après avoir confirmé le chemin du dépôt, le nom de la branche, la branche de base, le comportement d’installation des dépendances et la politique de nettoyage.

Modèle de prompt pour de meilleurs résultats avec git-worktree-manager

Prompt faible :

Set up a worktree for my feature.

Prompt plus efficace :

Use git-worktree-manager to prepare a new worktree for branch feature/billing-webhooks from main in repo /Users/me/app. Name it wt-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.

Ce prompt donne à la skill assez d’informations pour choisir la stratégie de branche, éviter les collisions de ports, rester prudente avec les fichiers .env* et séparer la planification de l’exécution.

FAQ de la skill git-worktree-manager

git-worktree-manager est-il réservé aux agents IA ?

Non. La skill est optimisée pour le travail multi-agent, mais les scripts et conventions sont également utiles aux développeurs humains. Le principal bénéfice est la reproductibilité : chaque worktree reçoit une branche, un répertoire, des ports, des fichiers d’environnement copiés et une revue de nettoyage prévisibles, plutôt qu’un historique shell improvisé.

En quoi est-ce différent d’un simple git worktree ?

La commande git worktree add crée un autre checkout. Elle ne résout pas les conflits d’application locale. git-worktree-manager ajoute le workflow autour : blocs de ports, .worktree-ports.json, copie des fichiers d’environnement, installation optionnelle des dépendances, conseils d’isolation Docker Compose et contrôles de nettoyage pour les branches obsolètes ou mergées.

Les débutants peuvent-ils l’utiliser sans risque ?

Oui, à condition de la considérer comme un workflow guidé plutôt que comme un exécuteur de commandes à lancer aveuglément. Les débutants devraient d’abord exécuter des opérations de liste ou de revue, utiliser --format text, éviter la suppression automatique et inspecter les commandes générées avant exécution. Le script de nettoyage vérifie les worktrees contenant des modifications non commitées, mais vous devez tout de même comprendre quelles branches peuvent être supprimées sans risque.

Quand ne faut-il pas utiliser cette skill ?

Ne l’utilisez pas telle quelle si votre dépôt a une gestion d’environnement atypique, des secrets qui ne doivent jamais être copiés, une installation de dépendances non standard ou des ports de services gérés par une plateforme interne. Dans ces cas, utilisez le git-worktree-manager guide comme point de départ et personnalisez les scripts ou les prompts avant adoption.

Comment améliorer la skill git-worktree-manager

Fournir davantage de contexte de dépôt à git-worktree-manager

De meilleurs inputs produisent des plans de worktree plus sûrs. Incluez :

• le chemin absolu du dépôt
• la branche cible et la branche de base
• le nom souhaité du répertoire de worktree
• le gestionnaire de paquets ou les lockfiles attendus
• les services qui ont besoin de ports
• si les fichiers .env* peuvent être copiés
• si l’installation des dépendances est autorisée
• le seuil d’âge pour le nettoyage et la branche de base pour les contrôles de merge

Cela réduit les suppositions et évite que l’agent applique des valeurs par défaut qui ne correspondent pas à votre application.

Ajuster les conventions de ports et de Docker Compose avec git-worktree-manager

La stratégie de référence utilise des bases par défaut comme l’application sur 3000, Postgres sur 5432, Redis sur 6379, avec un pas de 10 par worktree. Si votre stack comporte davantage de services, réservez un bloc contigu plus large. Si vous exécutez une infrastructure locale en dehors des worktrees, décalez les ports de base pour éviter les collisions globales.

Pour Docker Compose, privilégiez des overrides par worktree, des ports pilotés par .env et des noms de projet uniques, par exemple :

docker compose -p myapp_wt_auth up -d

Cela évite les collisions de conteneurs, réseaux, volumes et bases de données entre les branches.

Surveiller les modes d’échec courants

Les problèmes les plus fréquents sont les secrets copiés par erreur, la réutilisation des ports de base de données par défaut, les volumes Docker partagés entre des migrations incompatibles, l’installation de dépendances dans le mauvais runtime et la suppression d’un worktree contenant encore du travail non commité. Demandez à l’agent de signaler l’état dirty, les fichiers d’environnement copiés, les ports sélectionnés et les actions d’installation après chaque exécution.

Pour le nettoyage, commencez par une sortie en mode revue uniquement. N’activez la suppression qu’après avoir confirmé qu’un worktree est obsolète, propre et mergé dans la branche de base attendue.

Itérer après la première sortie

Après le premier plan ou la première commande, demandez une révision ciblée au lieu de repartir de zéro :

Revise the git-worktree-manager command to skip dependency installation, use base branch develop, reserve ports for app, Postgres, Redis, and Mailhog, and output JSON for automation.

Cela maintient la skill ancrée dans les contraintes réelles du dépôt tout en améliorant la sécurité et la reproductibilité.