Git worktrees : un seul cerveau, plusieurs agents en parallèle

Imaginez un repo unique regroupant plusieurs sujets distincts - un frontend, un backend, de l'infrastructure, la tuyauterie CI/CD - et plusieurs agents qui y travaillent en même temps, chacun sur sa branch. Vous voulez qu'ils avancent en parallèle sans se marcher dessus, et vous voulez une intelligence centrale capable de voir tout leur travail d'un coup : relire le diff d'un agent, intégrer celui d'un autre, résoudre un conflit, garder l'ensemble cohérent. Les réponses naïves échouent toutes les deux. Les worktrees de Git sont la réponse qui tient.

Le problème : un checkout ne contient qu'une branch

Un clone classique ne peut avoir qu'une seule branch active à la fois. Si l'agent A bascule le répertoire de travail sur sa branch, les fichiers de l'agent B changent sous ses pieds - vous avez mis tout le monde à la queue derrière un seul bureau. Le contournement évident, ce sont N clones complets, un par agent. Ça marche, mais chaque clone a son propre .git : une copie complète de l'historique, ses propres remotes, son propre état de fetch. Ils ne partagent pas les objets et s'ignorent localement, si bien que déplacer une branch de l'un à l'autre impose un aller-retour par le remote.

N clones dupliquent tout l'historique et ne peuvent échanger leur travail que par le remote. Les worktrees conservent un seul object store partagé : les branches cohabitent côte à côte et deux d'entre elles peuvent être comparées ou fusionnées localement.

Les worktrees, c'est la voie médiane : un seul repo - un seul .git, un seul object store, un seul jeu de branches - avec plusieurs répertoires de travail, chacun positionné sur une branch différente, tous actifs en même temps. L'état de travail est isolé, l'historique est partagé.

Ce qu'est réellement un worktree

Voyez un repo comme un cerveau et un bureau. Le cerveau, c'est .git : la base d'objets, les refs, la config. Le bureau, c'est le répertoire de travail : les fichiers que vous éditez réellement. Un clone classique fixe exactement un bureau sur un cerveau. Un worktree les découple - un seul cerveau, plusieurs bureaux.

Chaque bureau est un vrai répertoire sur le disque, positionné sur une branch, avec son propre HEAD et son propre index (la zone de staging). Mais ils partagent tous le même object store : aucun historique n'est dupliqué et le coût disque d'un bureau de plus est minime. Une règle protège tout le monde : la même branch ne peut pas être active dans deux worktrees à la fois. Git refuse, tout simplement - et ce refus est précisément ce qui empêche deux agents de corrompre une même branch.

Un seul object store .git contient tout l'historique et toutes les branches ; chaque répertoire de travail est positionné sur une branch différente avec son propre HEAD et son propre index. Ajoutez ou retirez des bureaux à moindre coût - le cerveau est partagé.

Comment ça marche

Toute l'interface tient dans une seule sous-commande. Depuis votre repo principal, vous ajoutez un bureau, vous le pointez sur une branch (nouvelle ou existante), et git crée le répertoire puis fait le checkout :

# vous etes dans le depot principal (le "main worktree")
cd ~/work/app

# un bureau pour l'agent backend, sur une branch toute neuve
git worktree add ../wt-backend -b feature/be-auth

# l'agent frontend, sa propre nouvelle branch
git worktree add ../wt-frontend -b feature/fe-redesign

# l'agent infra, depuis une branch existante
git worktree add ../wt-infra existing-infra-branch

git worktree list     # chaque bureau + la branch que chacun detient
git worktree remove ../wt-backend   # nettoyer une fois fini
git worktree prune    # supprimer les entrees admin obsoletes

Sur le disque, vous avez maintenant des répertoires frères - le repo principal, plus wt-backend, wt-frontend et wt-infra - chacun sur une branch différente. En coulisses, les bureaux secondaires ne portent pas un répertoire .git complet : ils contiennent un minuscule fichier .git qui renvoie vers le .git/worktrees/<name>/ du repo principal. Il n'y a toujours qu'un seul object store. Une branch créée dans un bureau est instantanément visible depuis tous les autres, parce qu'il n'y a qu'un seul repo.

Pourquoi c'est le bon socle pour plusieurs agents

L'object store partagé, c'est tout l'intérêt. Comme chaque branch vit dans une seule base, un agent coordinateur installé dans le main worktree peut travailler sur la production de tout le monde sans toucher au remote : git log --all voit l'ensemble, il peut faire le diff entre les branches de deux agents, cherry-pick de l'une à l'autre, merge, résoudre les conflits - le tout localement, instantanément.

Des modifications parallèles et isolées - chaque agent a son répertoire, donc aucune collision de fichiers.
Une branch par agent - imposé par git ; la même branch ne peut pas être active dans deux bureaux.
Création et suppression bon marché - les bureaux partagent les objets, donc en créer ou en retirer un prend quelques secondes.
Un cerveau central - un seul .git, donc une seule source de vérité sur laquelle l'orchestrateur peut raisonner : chaque branch, chaque commit, tout le log.
Builds et tests indépendants - chaque bureau a ses propres node_modules, sa propre sortie de build et ses propres caches, donc les agents font tourner leurs pipelines en même temps sans s'écraser les uns les autres.

Ce dernier point est facile à sous-estimer. Des répertoires de travail séparés, c'est un état de build séparé : un agent frontend peut lancer son serveur de dev pendant que l'agent infra applique du Terraform dans un bac à sable et que l'agent backend fait tourner sa suite de tests - sans qu'aucun ne se dispute les mêmes fichiers.

Façons de travailler

Les worktrees sont un socle, pas une méthode. Quelques schémas se transposent proprement sur de vraies équipes et de vraies flottes d'agents.

Orchestrateur et exécutants

Le main worktree est le cerveau central. Il lance un exécutant par worktree, chacun sur sa branch. Les exécutants committent sur leurs branches ; l'orchestrateur intègre - merge, rebase, cherry-pick entre elles, localement - puis push et ouvre les pull requests. C'est ce qui colle le mieux à "une intelligence, plusieurs agents".

L'orchestrateur vit dans le main worktree et voit toutes les branches d'un coup. Chaque agent travaille dans son bureau sur sa branch ; l'orchestrateur relit, merge localement, puis push et ouvre les PR.

Un worktree par sujet (durable) - wt-fe, wt-be, wt-infra, wt-cicd, des bureaux semi-permanents qui reflètent vos applications. Idéal quand les agents ou les équipes correspondent proprement aux sous-systèmes.
Un worktree par tâche (éphémère) - montez un bureau neuf pour chaque fonctionnalité ou bug, jetez-le au merge. Idéal quand le travail se découpe par tâche plutôt que par équipe.
Un worktree d'intégration - un bureau dédié où l'orchestrateur merge tout le monde en continu, pour détecter les conflits tôt. Votre canari du "est-ce que tout s'assemble toujours ?".

Dans Claude Code, c'est intégré

Si vous pilotez des agents avec Claude Code, le schéma des worktrees est natif, et non quelque chose à câbler à la main. Un sous-agent peut être lancé avec isolation par worktree - il s'exécute dans son propre worktree créé automatiquement et le bureau est nettoyé ensuite : c'est le schéma éphémère, automatisé. Il existe aussi des outils pour faire entrer et sortir la session courante d'un worktree. Du coup, "une intelligence centrale qui orchestre N agents sur N branches" devient : cette session est le cerveau dans le main worktree, chaque agent lancé reçoit son propre worktree isolé, et l'intégration se fait au retour dans le bureau principal.

Pièges à connaître

La même branch dans deux worktrees est bloquée - c'est voulu. Donnez à chaque bureau une branch distincte.
Les artefacts de build sont propres à chaque worktree - node_modules et consorts ne sont pas partagés, donc chaque bureau a besoin de sa propre installation. C'est en général ce qu'on veut pour l'isolation, mais cela coûte du disque et du temps, bien réels.
N'imbriquez pas un worktree dans le repo - sinon git tentera de le suivre comme des fichiers. Gardez les bureaux comme frères (../wt-*), et ignorez le motif si jamais vous les gardez à l'intérieur.
Utilisez git worktree remove, pas rm -rf - supprimer le dossier à la main laisse une entrée admin obsolète ; git worktree prune fait le ménage.
Les hooks et la config sont partagés - chaque bureau lit le même .git/config et les mêmes hooks. En général sans problème, parfois surprenant.
Les submodules ajoutent des frictions entre worktrees - si votre repo en utilise, attendez-vous à de la configuration supplémentaire par bureau.

Le modèle mental, c'est toute l'astuce : un seul cerveau, plusieurs bureaux. Cessez de voir un repo comme un dossier à l'intérieur duquel vous changez de branch, et voyez-le comme un historique partagé unique que n'importe quel nombre de répertoires de travail peuvent lire en même temps. C'est ce qui permet à une intelligence centrale de coordonner une flotte d'agents - chacun bien installé sur sa branch - pendant que l'historique qu'ils partagent tous reste la source de vérité unique.