Git Worktrees : le super-pouvoir que tes agents IA méritent

QU'EST-CE QU'UN GIT WORKTREE ?

Imagine un seul dépôt Git comme une maison avec plusieurs portes. Chaque porte donne sur une pièce différente (une branche), mais toutes les pièces partagent le même système de chauffage et d'électricité (le même historique Git). Un Git Worktree, c'est une de ces pièces : un répertoire séparé, mais qui utilise les mêmes données que les autres.

Dans cette image, tu vois quatre répertoires qui partagent le même dossier .git :

my-project/                    ← répertoire principal (branche: main)
my-project-feat-auth/          ← répertoire lié (branche: feat/auth)
my-project-feat-api/           ← répertoire lié (branche: feat/api)
my-project-hotfix-login/       ← répertoire lié (branche: hotfix/login)

Chaque répertoire est indépendant : un agent qui modifie un fichier dans my-project-feat-auth/ ne peut pas voir les changements dans my-project-feat-api/, même s'ils sont dans le même projet. C'est comme avoir quatre bureaux différents dans la même entreprise, chacun avec ses propres dossiers ouverts.

POURQUOI C'EST MIEUX QU'UN CLONE CLASSIQUE ?

La solution la plus simple pour isoler des agents serait de cloner le dépôt plusieurs fois. Mais ça a des problèmes évidents :

• ❌ Tu doubles l'espace disque utilisé (chaque clone pèse lourd).
• ❌ Les commits faits dans un clone n'apparaissent pas automatiquement dans l'autre.
• ❌ Pas de coordination possible entre les clones au niveau Git.

Avec les Git Worktrees, tu clones une seule fois. Chaque répertoire supplémentaire n'ajoute que le poids des fichiers modifiés, pas une copie complète de l'historique. C'est comme si tu avais un seul disque dur pour toute l'entreprise, mais chaque employé avait son propre bureau avec ses outils.

LES 7 COMMANDES INDISPENSABLES POUR GÉRER SES WORKTREES

Git propose seulement sept commandes pour tout gérer. Le reste, c'est du travail d'organisation autour de ces commandes.

Voici la liste complète :

git worktree add <chemin> -b <branche>

Crée un nouveau répertoire lié sur une nouvelle branche.

git worktree add <chemin> <branche-existante>

Crée un nouveau répertoire lié sur une branche déjà existante.

git worktree lock <chemin>

Verrouille un répertoire pour éviter qu'il soit supprimé accidentellement.

git worktree unlock <chemin>

Déverrouille un répertoire verrouillé.

git worktree remove <chemin>

Supprime proprement un répertoire lié (la branche Git reste intacte).

git worktree list

Affiche la liste de tous les répertoires liés avec leur branche et leur commit.

git worktree prune

Nettoie les métadonnées des répertoires qui ont été supprimés manuellement avec rm -rf.

COMMENT BIEN DÉMARRER ?

Avant de créer ton premier Git Worktree, assure-toi que ta branche principale est propre :

# Vérifie que tu n'as pas de modifications en cours
git status

# Si tu as des modifications non commitées, sauvegarde-les
git add . && git commit -m "checkpoint: travail en cours"

Pour créer un nouveau répertoire lié sur une nouvelle branche :

# Remplace "monprojet" par le nom de ton dépôt et "feat/auth" par le nom de ta branche
git worktree add -b feat/auth ./monprojet-feat-auth main

# Vérifie que ça a fonctionné
git worktree list

Résultat :

/home/user/monprojet            abc1234 [main]
/home/user/monprojet-feat-auth  abc1234 [feat/auth]

CONFIGURER UN WORKTREE POUR UN AGENT IA

Un Git Worktree est un répertoire vide au départ. Il ne contient pas automatiquement tes fichiers d'environnement (.env), tes dépendances (node_modules) ou ton environnement virtuel Python. Il faut tout configurer manuellement.

Exemple pour un projet Node.js :

cd ./monprojet-feat-auth

# Copie les fichiers d'environnement (ignoré par Git)
cp ./monprojet/.env .env
cp ./monprojet/.env.local .env.local 2>/dev/null || true

# Installe les dépendances (chaque worktree est indépendant)
npm install

Pour un projet Python :

# Crée et active un environnement virtuel
python -m venv .venv && source .venv/bin/activate && pip install -r requirements.txt

TESTER L'ISOLATION : UN CHANGEMENT DANS UNE BULLE NE TOUCHE PAS LES AUTRES

Pour vérifier que chaque Git Worktree est bien isolé :

# Dans le nouveau répertoire lié
cd ./monprojet-feat-auth
git branch
# Devrait afficher : * feat/auth

# Fais une modification de test
echo "// test" >> test-isolation.js
git status
# Ne montre que les changements dans ce répertoire lié

# Retourne dans le répertoire principal et vérifie que rien n'a changé
cd ./monprojet
git status
# Tout est propre -- le changement dans test-isolation.js est invisible ici
ls test-isolation.js 2>/dev/null || echo "Pas ici -- isolation confirmée"

LE CAS CONCRET QUI A TOUT CHANGÉ : MICROSOFT GLOBAL HACKATHON 2025

Tamir Dresher, un responsable technique, a été confronté à un problème classique en développement IA : trop de fonctionnalités à développer, pas assez de temps, et impossible de faire travailler plusieurs agents IA en parallèle sans tout mélanger.

Sa solution ? Utiliser les Git Worktrees pour créer une équipe de développement virtuelle. Chaque fonctionnalité a eu son propre répertoire lié, chaque répertoire avait sa propre fenêtre VS Code, et chaque fenêtre exécutait son propre agent IA.

Voici à quoi ressemblait son organisation :

monprojet/                       ← fenêtre principale : coordination et revues
monprojet-feat-authentication/   ← Agent 1 : implémentation du flux OAuth2
monprojet-feat-api-endpoints/    ← Agent 2 : création des endpoints REST
monprojet-bugfix-login-crash/    ← Agent 3 : correction d'un bug de production

Chaque fenêtre VS Code était complètement indépendante : les serveurs de langage, les linters et les runners de tests s'exécutaient par fenêtre. Les agents n'ont jamais touché aux fichiers des autres. Quand un agent terminait son travail, Dresher revoyait les modifications, approuvait, et ouvrait une pull request depuis cette branche — exactement comme pour un développeur humain.

LES 3 AVANTAGES CONCRETS DOCUMENTÉS

Dresher a documenté trois bénéfices majeurs :

1. Parallélisation sans limite : Plusieurs agents peuvent travailler simultanément sur des fonctionnalités différentes sans jamais se marcher dessus.
2. Contexte préservé : Chaque agent garde son propre contexte de travail. Pas besoin de tout réexpliquer quand on revient après une interruption.
3. Revues de code simplifiées : Les pull requests sont plus faciles à relire car chaque agent ne modifie que sa propre partie du code.

LE WORKFLOW COMPLET EN 4 ÉTAPES

Voici comment organiser le travail avec plusieurs agents IA en utilisant les Git Worktrees :

1. CRÉATION DES RÉPERTOIRES LIÉS

Tu peux créer un répertoire lié sur une nouvelle branche :

git worktree add -b feat/paiements ./monprojet-paiements main

Ou sur une branche existante :

git worktree add ./monprojet-feat-auth feat/auth

Pour déboguer un bug à un commit précis (utile pour reproduire un problème) :

git worktree add --detach ./monprojet-debug abc1234

Pour suivre directement une branche distante :

git worktree add ./monprojet-hotfix origin/hotfix/login-crash

2. CONFIGURATION DES ENVIRONNEMENTS

Dans chaque répertoire lié, configure ton environnement :

• Copie les fichiers .env, .env.local, etc.
• Installe les dépendances (npm install, pip install, etc.).
• Configure ton IDE pour qu'il utilise les bons outils.

Crée un fichier .worktreeinclude dans la racine de ton dépôt pour automatiser la copie des fichiers d'environnement dans chaque nouveau répertoire lié :

.worktreeinclude
# Fichiers à copier dans chaque nouveau worktree
.env
.env.local
.env.development

3. TRAVAIL DES AGENTS IA

Lance ton agent IA dans le répertoire lié approprié. Par exemple, avec Claude Code :

claude --worktree feat/auth-redesign
# Forme courte
claude -w feat/auth-redesign
# Avec des panneaux tmux pour une visibilité en split-screen
claude -w feat/auth-redesign --tmux

L'agent travaille dans son propre espace, sans voir les autres répertoires liés. Quand il a terminé :

# 1. Commite le travail de l'agent
git add .
git commit -m "feat: implémentation du flux OAuth2 + PKCE"

# 2. Synchronise avec la branche principale avant d'ouvrir une PR
./sync-worktree.sh

# 3. Lance les tests pour vérifier que rien n'a cassé pendant la synchronisation
npm run test

# 4. Pousse la branche
git push --force-with-lease origin feat/auth-redesign

# 5. Ouvre une pull request
# Soit via l'interface web, soit avec la CLI GitHub
gh pr create \
  --title "feat: authentification OAuth2 + PKCE" \
  --body "Implémente OAuth2 selon docs/auth-spec.md. Tous les tests passent."

4. NETTOYAGE APRÈS LA MERGE

Une fois la pull request mergée, nettoie le répertoire lié :

cd ./monprojet
./cleanup-worktree.sh feat/auth-redesign

AUTOMATISER LA CRÉATION DE PLUSIEURS WORKTREES EN UNE COMMANDE

Créer plusieurs répertoires liés un par un, c'est long. Voici un script Bash pour tout faire d'un coup :

chmod +x parallel-setup.sh
./parallel-setup.sh feat/auth feat/api feat/dashboard

Voici le contenu du script parallel-setup.sh :

#./usr/bin/env bash
# parallel-setup.sh
# Crée N répertoires liés pour N agents IA en une seule commande
# Utilisation : ./parallel-setup.sh   . 
# Exemple : ./parallel-setup.sh feat/auth feat/api feat/dashboard

set -euo pipefail

if [ $# -eq 0 ]; then
  echo "Utilisation : $0   . "
  echo "Exemple : $0 feat/auth feat/api feat/dashboard"
  exit 1
fi

REPO_ROOT="$(git rev-parse --show-toplevel)"
REPONAME="$(basename "$REPOROOT")"
MAIN_BRANCH="main"

echo "Configuration de ${#@} répertoires liés en parallèle."
git fetch origin 2>/dev/null || echo "(pas de remote -- saut du fetch)"

for BRANCH in "$@"; do
  SAFE="${BRANCH//\//-}"
  WTPATH="${REPOROOT}/./${REPO_NAME}-${SAFE}"

  if [ -d "$WT_PATH" ]; then
    echo "Déjà existant : $WT_PATH (sauté)"
    continue
  fi

  # Crée le répertoire lié sur une nouvelle branche depuis main
  git worktree add -b "$BRANCH" "$WTPATH" "$MAINBRANCH" 2>/dev/null || \
    git worktree add "$WT_PATH" "$BRANCH"

  # Copie les fichiers d'environnement
  for f in .env .env.local; do
    [ -f "$REPOROOT/$f" ] && cp "$REPOROOT/$f" "$WT_PATH/$f"
  done

  echo "Créé : $WT_PATH  (branche: $BRANCH)"
done

echo ""
echo "Tous les répertoires liés :"
git worktree list
echo ""
echo "Ouvre chaque chemin dans un terminal ou une fenêtre IDE séparée et lance ton agent."
echo "N'oublie pas de remplir la section 'Tâche en cours' du fichier AGENTS.md dans chaque répertoire lié."

UN FICHIER POUR GUIDER TES AGENTS IA : AGENTS.MD

Crée un fichier AGENTS.md dans la racine de ton dépôt. Ce fichier sera lu par chaque agent IA qui ouvre le projet, lui donnant tout le contexte nécessaire pour travailler efficacement.

Exemple de contenu :

# AGENTS.md
# Contexte du projet pour les agents IA
# Commite ce fichier à la racine de ton dépôt.
# Chaque agent qui ouvre ce projet le lit en premier.

## Aperçu du projet
API REST Node.js/TypeScript avec une interface React.
Stack : Node 20, Express 5, Prisma ORM, PostgreSQL, React 18, Vite.

## Commandes de build et de test
npm run dev          # lance le serveur de dev sur le port 3000
npm run build        # build de production dans dist/
npm run test         # lance tous les tests (Vitest)
npm run test:watch   # mode watch
npm run lint         # vérification ESLint et Prettier
npm run db:migrate   # exécute les migrations Prisma en attente
npm run db:seed      # injecte des données de développement

## Architecture
- Routes API :      src/routes/        un fichier par ressource
- Logique métier :   src/services/      jamais dans les gestionnaires de routes
- Accès base de données : src/repositories/  ne jamais appeler Prisma directement depuis les services
- Types partagés :   src/types/index.ts

## Conventions
- Toutes les fonctions exportées nécessitent des commentaires JSDoc
- Pas de console.log dans le code commité -- utilise src/utils/logger.ts
- Gestion des erreurs : lance des erreurs typées depuis les services, capture dans les gestionnaires de routes
- Nommage des branches : feat/, fix/, refactor/

## Zones interdites -- NE PAS MODIFIER sauf instruction explicite
- src/auth/              (propriété de l'équipe sécurité, processus de revue séparé)
- prisma/migrations/     (à modifier uniquement via npm run db:migrate)
- fichiers .env          (ne jamais commiter, ne jamais lire en dehors de config/)

## Tâche en cours dans ce répertoire lié
Tâche :                 [À REMPLIR avant de lancer l'agent]
Branche :               [À REMPLIR]
Critères d'acceptation : [À REMPLIR]

SYNCHRONISER UN WORKTREE AVEC LA BRANCHE PRINCIPALE

Quand un agent travaille longtemps sur une branche, il faut régulièrement synchroniser son travail avec la branche principale pour éviter les conflits. Voici un script pour automatiser ça :

chmod +x sync-worktree.sh
./sync-worktree.sh

Voici le contenu du script sync-worktree.sh :

#./usr/bin/env bash
# sync-worktree.sh
# Rebase la branche du répertoire lié actuel sur la dernière version de main
# Lance-le à des points clés pour éviter les divergences de branche
# Utilisation (depuis l'intérieur du répertoire lié) : ./sync-worktree.sh [nom-branche-principale]
# Exemple : ./sync-worktree.sh main

set -euo pipefail

MAIN_BRANCH="${1:-main}"
CURRENT_BRANCH="$(git rev-parse --abbrev-ref HEAD)"

if [ "$CURRENTBRANCH" = "$MAINBRANCH" ]; then
  echo "Déjà sur $MAIN_BRANCH -- rien à synchroniser."
  exit 0
fi

echo "Synchronisation de '$CURRENTBRANCH' sur '$MAINBRANCH'."

# Rejette si des modifications non commitées existent -- le rebase nécessite un état propre
if . git diff --quiet || . git diff --cached --quiet; then
  echo "ERREUR : modifications non commitées détectées."
  echo "Commite tes progrès d'abord :"
  echo "  git add . && git commit -m 'checkpoint: progression de l'agent'"
  exit 1
fi

# Récupère le dernier état distant
git fetch origin

# Rebase cette branche sur la dernière version de main
# --autostash gère automatiquement les petites différences dans l'arbre de travail
git rebase "origin/$MAIN_BRANCH" --autostash

echo ""
echo "Fait. '$CURRENTBRANCH' est à jour avec origin/$MAINBRANCH."
echo ""
echo "Quand tu es prêt à pousser :"
echo "  git push --force-with-lease"
echo ""
echo "Note : --force-with-lease est plus sûr que --force."
echo "Il refuse de pousser si quelqu'un d'autre a poussé sur cette branche depuis ton dernier fetch."

GÉRER LES PROBLÈMES COURANTS

Voici les erreurs les plus fréquentes et comment les résoudre :

fatal: 'feat/auth' is already checked out

Solution : Supprime le répertoire lié existant avec git worktree remove ou utilise un autre nom pour le nouveau répertoire.

fatal: <chemin> already exists

Solution : Supprime le répertoire existant ou choisis un autre chemin.

error: '.' is a main worktree

Solution : Ne touche pas au répertoire principal. Utilise git worktree remove uniquement sur les répertoires liés.

error: worktree has modified files

Solution : Commite ou stash les modifications avant de supprimer le répertoire lié. Si tu es sûr de vouloir supprimer sans commiter, utilise git worktree remove --force.

POURQUOI LES ÉQUIPES IA ONT BESOIN DE CET OUTIL ?

En 2025, 51% des développeurs professionnels utilisent des outils d'IA quotidiennement. Pourtant, seulement 17% de ceux qui utilisent des agents IA disent que ces outils ont amélioré la collaboration d'équipe. La différence ne vient pas des outils eux-mêmes, mais de l'infrastructure en dessous.

Les équipes ont adopté les agents IA sans mettre en place la couche de travail nécessaire. Ce guide est cette couche manquante. Les Git Worktrees permettent :

• ✅ Plusieurs agents travaillant en parallèle sans conflit.
• ✅ Un contexte préservé pour chaque agent.
• ✅ Des revues de code plus simples et plus ciblées.
• ✅ Une organisation claire du travail (chaque fonctionnalité dans son propre espace).

Sans ça, tu passes ton temps à éteindre des incendies : un agent écrase les modifications d'un autre, un bug de production doit être corrigé immédiatement et tout le contexte des agents est perdu, les conflits de merge deviennent ingérables. Les Git Worktrees éliminent toute cette classe de problèmes.

LE VERDICT : UN OUTIL DE 2015 QUI DEVIENT ESSENTIEL EN 2025

Les Git Worktrees existent depuis Git 2.5 (2015), mais leur utilité a explosé avec l'arrivée des agents IA. Ce n'est pas un outil révolutionnaire, mais une infrastructure invisible qui rend le travail avec plusieurs agents IA possible, propre et efficace.

Si tu utilises des agents IA pour coder, Git Worktrees ne sont plus une option, mais une nécessité. Ils transforment une source de chaos potentiel en un système organisé et scalable. Une fois que tu as essayé, tu ne pourras plus t'en passer.