Un worktree Git est un répertoire de travail supplémentaire rattaché à un dépôt Git existant. Il possède sa propre branche extraite, son propre index et ses propres fichiers non suivis, tout en partageant la base d'objets, les références et la configuration du dépôt principal. Pour des agents de développement opérant en parallèle, il s'agit de l'unité d'isolation idéale : chaque agent dispose d'un dossier exclusif où nul autre n'intervient, ses commits s'inscrivent sur une branche dédiée, et la création de l'environnement est une extraction quasi-instantanée plutôt qu'un clone fastidieux ou un démarrage de conteneur. Cet article détaille les commandes clés, pourquoi les worktrees surpassent le répertoire partagé, les pièges à éviter et comment Ivy Tendril crée et supprime un worktree par tâche.
Définition d'un worktree Git
Par défaut, tout dépôt Git dispose d'un unique répertoire de travail. La commande git worktree add permet d'en raccorder d'autres. Chacun constitue une copie de travail autonome dans laquelle vous pouvez vous déplacer avec cd, apporter des modifications, compiler et committer.
# Créer un worktree dans le dossier parent sur une nouvelle branche
git worktree add ../feature-x -b feature-x
# Lister les worktrees rattachés au dépôt
git worktree list
# /Users/dev/app a1b2c3d [main]
# /Users/dev/feature-x a1b2c3d [feature-x]
Le nouveau dossier intègre un fichier .git (et non un sous-dossier). Celui-ci renvoie vers .git/worktrees/feature-x dans le dépôt principal, où sont gérés l'index et le pointeur HEAD associés. Objets, références, hooks Git et configurations sont lus à la source. Un commit généré dans ../feature-x est immédiatement accessible depuis le dépôt initial via git log feature-x, sans push ni fetch.
Deux contraintes découlent de cette architecture : une branche ne peut être extraite que dans un seul worktree à la fois, et le dossier du worktree doit impérativement se situer en dehors du dossier de travail principal afin de ne pas être interprété comme un ensemble de fichiers non suivis.
Pourquoi les worktrees surpassent le répertoire partagé
Un agent de code lit, modifie des fichiers, exécute des tests et committe. Si deux agents interviennent simultanément dans le même dossier, ils génèrent un diff mélangé ingérable, et aucun jeu de tests ne peut évaluer leurs travaux de manière étanche. Les alternatives sont un clone complet par agent, un conteneur Docker par agent ou un worktree par agent.
| Approche | Arborescence & branche privées | Base d'objets partagée | Coût de démarrage | Isolation d'exécution |
|---|---|---|---|---|
| Répertoire partagé | Non | Oui | Nul | Nulle |
| Clone complet par agent | Oui | Non (duplication totale) | Clonage + installation dépendances | Nulle |
| Conteneur par agent | Oui | Non (sauf montage) | Pull d'image + démarrage conteneur | Oui |
| Worktree par agent | Oui | Oui | Extraction immédiate | Nulle |
Le worktree apporte aux agents ce qui est strictement nécessaire à la justesse de leur tâche (une arborescence et une branche réservées), sans la lourdeur d'une virtualisation complète. La base d'objets étant mutualisée, un projet cumulant des années d'historique ne coûte que l'extraction de l'état présent. Les caches des gestionnaires de paquets (pnpm, Cargo, NuGet) restent centralisés dans le répertoire utilisateur.
Les conteneurs Docker demeurent appropriés lorsque les agents doivent modifier l'environnement système ou lier des ports réseau. Les deux approches sont d'ailleurs complémentaires : un worktree peut aisément être monté dans un conteneur. Pour les tâches courantes d'édition et de tests, le worktree natif suffit amplement.
Pour une vision globale, consultez les modèles d'orchestration d'agents.
Pièges classiques et bonnes pratiques
Si les worktrees éliminent les conflits de répertoires, ils ne dispensent pas d'une gestion rigoureuse sur trois aspects fondamentaux.
1. Deux agents modifiant les mêmes fichiers sur des branches distinctes
Les worktrees isolent les dossiers, non les intentions architecturales. Si deux plans touchent concurremment à auth/session.ts, chaque branche committera sans encombre, mais la seconde fusion déclenchera un conflit de merge. Ce problème doit être anticipé lors du cadrage : identifiez les dépendances amont et sérialisez les plans ou découpez-les par module exclusif.
2. Répertoires avec modifications non commitées (Dirty Trees)
Si un agent s'arrête brutalement ou si un test génère des résidus, le worktree conserve des fichiers non suivis. git worktree remove refuse par sécurité de détruire un répertoire non nettoyé. Un orchestrateur robuste prendra soin de committer l'ensemble des artefacts produits sur la branche de travail afin de ne rien égarer avant de supprimer le worktree.
# Inspecter les fichiers résiduels
git -C ../feature-x status --short
# Supprimer un worktree propre
git worktree remove ../feature-x
# Forcer la suppression après contrôle
git worktree remove --force ../feature-x
3. Worktrees abandonnés
Les worktrees créés manuellement ont tendance à proliférer, bloquant des branches et occupant du stockage. Si un dossier est détruit par un simple rm -rf au lieu de git worktree remove, Git conserve des enregistrements fantômes dans .git/worktrees/.
# Simuler le nettoyage
git worktree prune --dry-run --verbose
# Élaguer les références orphelines
git worktree prune
La règle universelle est claire : le système qui initialise un worktree doit également orchestrer sa suppression à une étape précise du cycle de vie.
L'implémentation des worktrees par Ivy Tendril
Ivy Tendril est une application de bureau locale (macOS, Windows, Linux) pilotant les agents de développement du plan initial jusqu'à la pull request validée. Les worktrees en constituent l'unité d'exécution. Consultez la présentation produit et la documentation du cycle de vie.
- Un worktree par plan : Dès l'approbation d'un plan, Tendril génère automatiquement son worktree et sa branche. Plusieurs dizaines de plans peuvent tourner en parallèle sans affecter main.
- Vérification étanche : Tests, linter et calcul du diff s'exécutent strictement dans le périmètre du worktree. L'écran de revue met en regard le diff et les résultats des tests.
- Suppression post-merge : Dès l'intégration de la pull request sur GitHub, Tendril supprime proprement le worktree sans action manuelle requise.
- Indépendance d'agents : Compatible avec Claude Code, Codex CLI, Copilot CLI, Gemini CLI ou OpenCode.
- Respect absolu du local : Fichiers, plans et logs demeurent cantonnés à votre poste. Voir développement IA en local-first.
Déployez vos agents avec Ivy Tendril
Offrez à vos équipes une infrastructure de développement parallèle robuste et sécurisée :
- Consulter le code : Accédez à Ivy Tendril sur GitHub (open source).
- Lire les documentations : Explorez l'ensemble des guides sur tendril.ivy.app.
- Consulter nos experts : Écrivez à renco@ivy.app pour programmer un échange d'architecture de 30 minutes.