Comment utiliser Git worktrees avec des agents IA ?

J’utilise Git worktrees pour donner à chaque agent IA son propre espace de travail, sans recloner tout le dépôt. Ça évite les collisions, les pertes de contexte et les hotfixes qui écrasent tout. Le vrai sujet, c’est d’isoler vite sans casser votre workflow Git.

C’est quoi un Git worktree ?

Un Git worktree est un dossier de travail séparé, relié au même dépôt Git, qui partage les objets et l’historique mais garde son propre état de fichiers et son propre index.

Dit plus simplement, vous avez un même dépôt Git en dessous, avec les mêmes commits, les mêmes objets, les mêmes références, mais plusieurs dossiers dans lesquels vous pouvez travailler en parallèle. Chaque dossier a sa branche active, ses fichiers visibles à l’instant T, et son index. L’index, c’est la zone intermédiaire de Git, celle où vous mettez les fichiers avec git add avant de faire un commit.

La confusion vient souvent du mot “dépôt”. Dans la pratique, il y a plusieurs couches.

Élément	Rôle
Dépôt partagé	Contient l’historique Git, les commits, les branches, les objets.
Répertoire de travail	Contient les fichiers que vous éditez dans un dossier donné.
Index	Prépare ce qui va entrer dans le prochain commit.
Branche active	Dit sur quelle ligne de travail ce dossier est positionné.

Avec des worktrees, je peux avoir une organisation comme ça :

mon-projet/
mon-projet-agent-refacto/
mon-projet-agent-tests/
mon-projet-hotfix/

Le dossier mon-projet peut rester sur main. Le dossier mon-projet-agent-refacto peut être sur une branche agent/refacto. Le dossier mon-projet-agent-tests peut être sur agent/tests. Le dossier mon-projet-hotfix peut être sur hotfix/paiement. Chaque agent IA, ou chaque développeur, bosse dans son propre espace, sans écraser les fichiers des autres, sans devoir stash toutes les dix minutes.

Et c’est important : un worktree n’est pas un clone complet. Vous ne recopiez pas tout l’historique Git à chaque fois. Les worktrees partagent le même stockage Git, donc c’est plus léger, plus propre, et les branches restent coordonnées dans le même dépôt.

Dans les projets où plusieurs agents IA ou plusieurs développeurs interviennent vite, je le vois souvent : le problème n’est pas Git lui-même. Le vrai problème, c’est le mélange des contextes dans un seul dossier. Un agent refactore, un autre modifie les tests, quelqu’un doit corriger un bug urgent, et tout se retrouve au même endroit. Avec les worktrees, chacun a son terrain de jeu, mais tout reste relié au même historique.

Pourquoi c’est utile avec l’IA ?

Avec des agents IA, Git worktrees sert surtout à éviter qu’un agent modifie le même espace de travail qu’un autre, ou qu’un hotfix vienne perturber une tâche déjà lancée.

Le scénario classique, je le vois souvent. Un agent travaille sur une branche pour refactorer une partie du code. Un autre doit corriger un bug urgent. Un troisième génère des tests. Sur le papier, tout va vite. Dans la vraie vie, si tout le monde partage le même dossier, ça devient fragile.

On change de branche. On garde des fichiers modifiés. On a des dépendances installées pour une tâche mais pas pour l’autre. L’agent croit encore être dans son contexte initial, alors que le code sous ses pieds a changé. Et là, il peut écraser des changements, perdre le fil, ou proposer une correction qui mélange deux sujets différents.

Avec Git worktrees, chaque agent peut avoir son propre dossier, sa propre branche, ses fichiers modifiés et son état de travail. Un worktree, c’est simplement un espace de travail séparé qui pointe vers le même dépôt Git. Donc l’agent A peut avancer sur feature-import, l’agent B peut corriger hotfix-login, et l’agent C peut écrire des tests sur tests-api, sans se marcher dessus.

Le point important, c’est que les commits restent visibles dans le même dépôt Git. On garde la coordination. On ne crée pas trois mondes parallèles impossibles à réconcilier. Chaque branche vit dans son dossier, mais l’historique Git reste partagé.

L’approche naïve, c’est de cloner plusieurs fois le même dépôt. Ça marche, oui. Mais c’est plus lourd. On duplique l’historique, on consomme plus de disque, et on finit avec plusieurs clones à synchroniser. Avec les worktrees, seuls les fichiers de travail sont présents dans chaque dossier. Les objets Git, c’est-à-dire les commits, les branches et l’historique interne, sont partagés.

Quand je vois des équipes brancher des agents IA sur un dépôt unique sans isolation, les premiers gains de temps disparaissent vite. Pas à cause de l’IA elle-même. À cause des corrections manuelles derrière, des conflits inutiles, et du temps passé à comprendre qui a modifié quoi.

Critère	Clones multiples	Git worktrees
Isolation	Bonne, mais chaque clone vit séparément.	Bonne, avec un dossier et une branche par agent.
Stockage	Plus lourd, l’historique est dupliqué.	Plus léger, les objets Git sont partagés.
Visibilité des commits	Moins directe, il faut synchroniser les clones.	Directe, tout reste dans le même dépôt Git.
Simplicité de nettoyage	Moins propre, on supprime des dossiers complets.	Plus propre, on retire un worktree quand la tâche est finie.

Quelles commandes faut-il connaître ?

La plupart des usages tiennent avec sept commandes Git worktree. Pas besoin de connaître tout Git par cœur. Dans la vraie vie, surtout avec des agents IA, je veux juste créer un espace propre, lancer le travail, vérifier ce qui existe, puis nettoyer sans casser le dépôt principal.

Les commandes à garder sous la main sont celles-ci :

git worktree add <path> -b <branch>	Crée un nouveau dossier de travail avec une nouvelle branche. C’est celle que j’utilise le plus pour donner une tâche isolée à un agent IA.
git worktree add <path> <existing-branch>	Crée un worktree depuis une branche qui existe déjà. Pratique si vous voulez reprendre un chantier sans toucher à votre dossier principal.
git worktree list	Affiche les worktrees actifs. Simple, mais indispensable quand plusieurs agents tournent en parallèle.
git worktree lock <path>	Protège un worktree contre une suppression accidentelle. Je le fais quand un agent IA travaille encore dessus, surtout sur des tâches longues.
git worktree unlock <path>	Retire le verrou. À utiliser quand le travail est terminé ou quand vous voulez supprimer le dossier proprement.
git worktree remove <path>	Supprime proprement le dossier de travail, mais garde la branche. C’est important, vous ne perdez pas l’historique Git.
git worktree prune	Nettoie les métadonnées Git quand un dossier de worktree a été supprimé à la main. Ça arrive, même aux gens sérieux.

Il y a une règle Git à connaître : une même branche ne peut généralement pas être checkout dans deux worktrees en même temps. Dit autrement, vous ne pouvez pas avoir deux dossiers différents qui modifient tous les deux la branche main en parallèle. C’est volontaire. Ça évite pas mal de confusions, surtout quand un agent IA pousse du code pendant que vous corrigez autre chose.

Un exemple très classique : je crée un espace pour un agent IA qui ajoute des tests, puis un autre pour un hotfix urgent.

git worktree add ../agent-tests -b ai/add-login-tests
git worktree add ../hotfix-payment -b hotfix/payment-timeout

git worktree list

git worktree lock ../agent-tests

Le dossier ../agent-tests peut être donné à l’agent IA. Le dossier ../hotfix-payment reste pour moi, avec une branche claire et isolée. C’est bête, mais ça change tout : moins de stress, moins de conflits, moins de “attends, j’étais sur quelle branche déjà ?”.

Comment le mettre en place proprement ?

Je démarre toujours depuis un dépôt propre, puis je crée un worktree par tâche ou par agent IA. C’est la base qui évite 80% des problèmes bêtes, surtout quand plusieurs agents touchent au code en parallèle.

Avant de faire quoi que ce soit, je vérifie deux choses. D’abord la version de Git, parce que les worktrees existent depuis Git 2.5. Ensuite l’état du dépôt principal, pour être sûr que je ne pars pas avec des fichiers modifiés sans le vouloir.

git --version
git status

Si git status me dit que le dépôt est propre, parfait. Si j’ai déjà du travail en cours, je ne crée pas un worktree par-dessus un état flou. Je fais soit un commit, soit un stash. Le commit “checkpoint” est souvent le plus simple quand je veux garder une trace claire.

git add . && git commit -m "checkpoint: work in progress"

Le message peut être adapté, bien sûr. L’idée n’est pas d’avoir le commit parfait. L’idée, c’est de ne pas lancer un agent IA dans un contexte ambigu, avec des changements à moitié faits et personne qui sait vraiment ce qui appartient à quoi. J’ai vu ça chez un client, deux agents avaient modifié les mêmes fichiers depuis un dépôt déjà sale. Résultat, personne ne savait quelle modification venait d’où.

Le flux simple que j’utilise ressemble à ça. Un dépôt principal propre, puis un dossier par intention de travail.

# Depuis le dépôt principal
git status

# Un worktree pour un agent qui travaille sur les tests
git worktree add ../project-agent-tests -b agent/tests

# Un autre worktree pour un hotfix isolé
git worktree add ../project-hotfix -b hotfix/payment-bug

Ensuite, je lance chaque agent dans son dossier. Pas dans le dépôt principal.

cd ../project-agent-tests
# Lancer ici l'agent IA dédié aux tests

cd ../project-hotfix
# Lancer ici l'agent IA dédié au correctif

Quand un worktree ne sert plus, je peux supprimer le dossier proprement avec Git.

git worktree remove ../project-agent-tests

Point important, et ça rassure souvent les équipes : git worktree remove supprime le dossier de travail, mais la branche reste disponible. Le travail n’est pas perdu tant qu’il a été commité sur la branche.

Ma règle pratique est simple : un dossier par intention de travail. Si une tâche mérite son propre contexte, elle mérite souvent son propre worktree.

Quelles erreurs éviter ?

Les erreurs viennent surtout d’un mauvais nommage, d’un nettoyage manuel trop rapide, ou d’agents IA lancés sans règle claire. J’ai vu ça plusieurs fois chez des clients : au début c’est propre, chacun a son petit worktree, puis trois semaines après personne ne sait quel dossier sert encore à quelque chose.

Les pièges les plus fréquents sont assez simples à éviter :

• Créer trop de worktrees sans convention de nommage.
• Supprimer un dossier à la main au lieu d’utiliser git worktree remove.
• Oublier de lancer git worktree prune après une suppression manuelle.
• Laisser des worktrees morts, avec des branches qui ne bougent plus.
• Ne pas verrouiller un worktree utilisé par un agent IA qui tourne longtemps.

Le point le plus sous-estimé, c’est le verrouillage. git worktree lock sert à dire à Git : “Ne touche pas à ce worktree, il est encore utilisé”. Dans un contexte IA, c’est très pratique. Si un agent travaille encore sur une correction, un refactor ou une série de tests, on évite qu’un humain ou un script de nettoyage supprime son environnement par erreur. C’est bête, mais ça arrive vite quand on automatise.

Je garde une convention très simple pour les dossiers. Je prends le nom du projet, le type de tâche, puis la branche ou le sujet. Par exemple : project-ai-tests, project-refactor-auth, project-hotfix-payment. Ce n’est pas magique, mais quand vous avez cinq agents ou trois devs qui bossent en parallèle, ça change tout.

Les worktrees ne remplacent pas une bonne discipline Git. Ils rendent juste l’isolation beaucoup moins pénible. Si vos branches sont mal nommées, si personne ne nettoie, ou si les agents IA créent des variantes dans tous les sens, ça devient vite un placard à dossiers.

Risque	Conséquence	Bonne pratique
Trop de worktrees sans convention	Personne ne sait quoi garder ou supprimer	Utiliser un nom clair : projet, tâche, branche
Suppression manuelle d’un dossier	Git garde une référence cassée	Utiliser git worktree remove
Références mortes non nettoyées	La liste des worktrees devient illisible	Lancer git worktree prune
Agent IA encore actif	Son environnement peut être supprimé par erreur	Verrouiller avec git worktree lock

Et si vos agents IA travaillaient chacun dans leur coin ?

Git worktrees règle un problème très concret : plusieurs tâches, plusieurs agents IA, un seul dépôt, et trop de risques de mélange. Je garde le même historique Git, je limite la duplication disque, je donne à chaque agent son dossier et sa branche, puis je nettoie proprement quand le travail est fini. Ce n’est pas une surcouche compliquée. C’est juste une façon plus propre d’organiser le développement assisté par IA, surtout quand les itérations vont vite. Le bénéfice pour vous est simple : moins de collisions, moins de contexte perdu, et un workflow Git beaucoup plus fiable.

FAQ

• Git worktrees sert à quoi exactement ?
  Git worktrees sert à créer plusieurs dossiers de travail reliés au même dépôt Git. Chaque dossier peut avoir sa branche, ses fichiers modifiés et son propre état, tout en partageant le même historique. C’est pratique quand plusieurs tâches avancent en parallèle.
• Pourquoi utiliser Git worktrees avec des agents IA ?
  Parce qu’un agent IA a besoin d’un contexte stable. Si vous changez de branche dans le même dossier pendant qu’un agent travaille, vous risquez de casser son raisonnement ou d’écraser des modifications. Avec un worktree par agent, chacun travaille dans son coin.
• Git worktrees remplace les branches Git ?
  Non, les worktrees ne remplacent pas les branches. Ils permettent plutôt d’utiliser plusieurs branches en parallèle dans plusieurs dossiers. La branche reste le mécanisme Git principal, le worktree apporte l’isolation physique du dossier.
• Quelle différence entre un worktree et un clone Git ?
  Un clone recrée un dépôt complet, avec son historique et ses objets Git. Un worktree partage ces objets avec le dépôt principal. Résultat : moins de duplication, moins de stockage consommé, et une coordination plus directe entre les branches.
• Est-ce que supprimer un worktree supprime la branche ?
  Non. Avec git worktree remove <path>, vous supprimez le dossier de travail, mais la branche est conservée. C’est justement ce qui rend le nettoyage assez rassurant. Le travail versionné reste dans Git.

 

 

A propos de l’auteur

Je suis Franck Scandolera, expert et formateur en tracking avancé server-side, Analytics Engineering, automatisation No/Low Code avec n8n, intégration de l’IA en entreprise et SEO/GEO. J’accompagne des équipes qui veulent brancher l’IA dans leurs vrais workflows, pas dans des démos propres sur slides. Avec webAnalyste et Formations Analytics, j’ai travaillé pour Logis Hôtel, Yelloh Village, BazarChic, la Fédération Française de Football, Texdecor et d’autres. Si vous voulez structurer vos automatisations, vos agents IA ou vos pipelines data sans créer une usine à gaz, contactez-moi.