Git Worktree : travailler sur plusieurs branches simultanément
Introduction
Vous êtes en plein développement d'une feature quand on vous demande de corriger un bug urgent en production. Que faites-vous ? git stash, switch de branche, fix, commit, re-switch, git stash pop... et parfois, des conflits au passage.
Git worktree résout élégamment ce problème. Cette fonctionnalité native de Git (depuis la version 2.5) permet de travailler sur plusieurs branches simultanément, chacune dans son propre répertoire, sans jamais quitter votre travail en cours.
Le problème sans worktree
Dans un workflow Git classique, un dépôt = un répertoire de travail = une seule branche active. Pour changer de contexte, vous devez :
- Sauvegarder votre travail en cours (
git stashou commit temporaire) - Changer de branche (
git checkoutougit switch) - Travailler sur l'autre branche
- Revenir à votre branche initiale
- Restaurer votre travail (
git stash pop)
Cela pose plusieurs problèmes :
- Perte de contexte : votre IDE recharge tout, les serveurs de dev redémarrent
- Risque d'erreurs : oublier un stash, conflits au pop, commits sur la mauvaise branche
- Temps perdu : rebuild des dépendances, recompilation, rechargement des outils
- Stash empilés : plusieurs stashs qui s'accumulent et deviennent difficiles à gérer
Qu'est-ce qu'un worktree ?
Un worktree (arbre de travail) est un répertoire lié à votre dépôt Git qui contient une copie de travail d'une branche spécifique. Chaque worktree :
- Possède son propre répertoire sur le disque
- Est lié à une branche différente
- Partage le même historique Git (même
.git) - Fonctionne de manière totalement indépendante
mon-projet/ ← worktree principal (branche main)
mon-projet-feature/ ← worktree secondaire (branche feature/login)
mon-projet-hotfix/ ← worktree secondaire (branche hotfix/bug-123)
Tous ces répertoires pointent vers le même dépôt Git. Un commit fait dans l'un est visible dans les autres.
Commandes essentielles
Créer un worktree
# Syntaxe de base
git worktree add <chemin> <branche>
# Créer un worktree pour une branche existante
git worktree add ../mon-projet-feature feature/login
# Créer un worktree ET une nouvelle branche
git worktree add -b feature/signup ../mon-projet-signup
# Créer un worktree basé sur une branche distante
git worktree add ../mon-projet-fix origin/hotfix/bug-456
Après exécution, un nouveau répertoire est créé avec le contenu de la branche spécifiée, prêt à l'emploi.
Lister les worktrees
git worktree list
Résultat :
/home/user/mon-projet abc1234 [main]
/home/user/mon-projet-feature def5678 [feature/login]
/home/user/mon-projet-hotfix ghi9012 [hotfix/bug-123]
Supprimer un worktree
# Supprimer un worktree (après avoir terminé le travail)
git worktree remove ../mon-projet-feature
# Forcer la suppression (si des modifications non commitées existent)
git worktree remove --force ../mon-projet-feature
Nettoyer les worktrees invalides
Si vous supprimez manuellement un répertoire de worktree (avec rm -rf), Git garde une référence orpheline. Pour nettoyer :
git worktree prune
Comment ça fonctionne en interne ?
Quand vous créez un worktree, Git :
- Crée le répertoire cible
- Y place un fichier
.git(pas un dossier) qui pointe vers le dépôt principal :
# Contenu du fichier .git dans un worktree secondaire
gitdir: /home/user/mon-projet/.git/worktrees/mon-projet-feature
- Crée une entrée dans
.git/worktrees/du dépôt principal avec les métadonnées du worktree
Le dépôt Git (.git/objects, .git/refs, etc.) est partagé. Cela signifie :
- Pas de duplication de l'historique (gain d'espace disque)
- Les commits faits dans un worktree sont immédiatement visibles dans les autres
- Les branches distantes (
git fetch) sont partagées
Cas d'usage concrets
1. Hotfix urgent pendant un développement
Le cas le plus classique : vous travaillez sur une feature et devez corriger un bug en production.
# Vous êtes sur feature/dashboard dans mon-projet/
# Créez un worktree pour le hotfix
git worktree add ../mon-projet-hotfix -b hotfix/fix-auth main
# Allez dans le worktree du hotfix
cd ../mon-projet-hotfix
# Corrigez le bug, commitez, pushez
git add .
git commit -m "fix: corriger l'authentification JWT expirée"
git push origin hotfix/fix-auth
# Retournez à votre feature, rien n'a changé
cd ../mon-projet
# Une fois le hotfix mergé, nettoyez
git worktree remove ../mon-projet-hotfix
Votre travail sur feature/dashboard n'a jamais été interrompu.
2. Review de pull request
Vous voulez tester localement la PR d'un collègue sans toucher à votre travail :
# Récupérer la branche de la PR
git fetch origin feature/new-api
# Créer un worktree dédié à la review
git worktree add ../review-new-api origin/feature/new-api
# Tester, lire le code, lancer les tests dans ce répertoire
cd ../review-new-api
npm install
npm test
# Nettoyer après la review
cd ../mon-projet
git worktree remove ../review-new-api
3. Comparer deux versions côte à côte
Besoin de comparer le comportement entre deux branches ?
# Worktree pour la version actuelle
git worktree add ../projet-v2 release/v2
# Worktree pour la nouvelle version
git worktree add ../projet-v3 release/v3
# Ouvrez les deux dans votre éditeur/navigateur et comparez
4. Exécuter des tests longs en parallèle
Si vos tests prennent du temps, lancez-les dans un worktree pendant que vous continuez à coder :
# Créer un worktree pour les tests
git worktree add ../mon-projet-tests feature/ma-feature
# Lancer les tests en arrière-plan
cd ../mon-projet-tests
npm test &
# Continuer à coder dans le worktree principal
cd ../mon-projet
# ... vos modifications ...
5. Build de production pendant le développement
Générez un build de production sans interrompre votre serveur de dev :
git worktree add ../mon-projet-build main
cd ../mon-projet-build
npm ci
npm run build
Règles et contraintes
Il y a quelques règles importantes à retenir :
Une branche = un seul worktree
Git interdit d'avoir deux worktrees sur la même branche :
git worktree add ../autre-main main
# Erreur : fatal: 'main' is already checked out at '/home/user/mon-projet'
C'est une protection contre les conflits : deux répertoires modifiant la même branche simultanément créeraient des incohérences.
Solution : créez une branche temporaire basée sur la branche souhaitée :
git worktree add -b temp/main-copy ../autre-main main
Les fichiers non suivis ne sont pas partagés
Chaque worktree a son propre ensemble de fichiers non suivis (untracked). Les fichiers comme node_modules/, .env, ou les builds locaux ne sont pas partagés entre worktrees.
Cela signifie que vous devrez réinstaller les dépendances (npm install) dans chaque nouveau worktree.
Le .gitignore est partagé
Le fichier .gitignore fait partie du dépôt, il s'applique donc à tous les worktrees.
Worktree vs autres approches
| Approche | Avantages | Inconvénients |
|---|---|---|
| git stash | Simple, rapide | Perte de contexte, risque de conflits |
| git clone (copie) | Isolation complète | Duplication du dépôt, historiques séparés |
| git worktree | Léger, branches partagées, pas de perte de contexte | Dépendances à réinstaller |
En résumé :
- Utilisez
git stashpour des changements de contexte rapides et courts - Utilisez
git worktreepour du travail parallèle prolongé - Utilisez
git clonesi vous avez besoin d'une isolation complète (rare)
Bonnes pratiques
1. Convention de nommage
Adoptez une convention claire pour vos répertoires de worktree :
# Convention : <projet>-wt-<description>
git worktree add ../learn-wt-hotfix hotfix/bug-123
git worktree add ../learn-wt-review feature/new-api
2. Regrouper les worktrees
Créez un répertoire parent pour garder les choses organisées :
mkdir -p ../worktrees
git worktree add ../worktrees/hotfix hotfix/bug-123
git worktree add ../worktrees/review feature/new-api
3. Nettoyer régulièrement
Les worktrees oubliés s'accumulent. Prenez l'habitude de :
# Lister les worktrees actifs
git worktree list
# Supprimer ceux qui ne sont plus nécessaires
git worktree remove ../worktrees/hotfix
# Nettoyer les références orphelines
git worktree prune
4. Automatiser l'installation des dépendances
Créez un petit script pour initialiser rapidement un worktree :
#!/bin/bash
# wt-create.sh : Créer et initialiser un worktree
BRANCH=$1
DIR=$2
git worktree add "$DIR" "$BRANCH"
cd "$DIR"
npm install
echo "Worktree prêt dans $DIR"
Intégration avec les éditeurs
VS Code
VS Code détecte automatiquement les worktrees. Ouvrez simplement le répertoire du worktree comme un projet normal :
code ../mon-projet-hotfix
Chaque fenêtre VS Code travaille indépendamment sur sa branche.
JetBrains (WebStorm, IntelliJ)
Les IDE JetBrains reconnaissent également les worktrees. Ouvrez le répertoire du worktree comme un projet distinct.
Résumé des commandes
| Commande | Description |
|---|---|
git worktree add <chemin> <branche> | Créer un worktree pour une branche existante |
git worktree add -b <nouvelle-branche> <chemin> [base] | Créer un worktree avec une nouvelle branche |
git worktree list | Lister tous les worktrees |
git worktree remove <chemin> | Supprimer un worktree |
git worktree prune | Nettoyer les références orphelines |
git worktree move <source> <destination> | Déplacer un worktree |
git worktree lock <chemin> | Verrouiller un worktree (empêcher le prune) |
git worktree unlock <chemin> | Déverrouiller un worktree |
Conclusion
git worktree est un outil sous-estimé qui peut transformer votre workflow quotidien. Au lieu de jongler entre les branches avec stash et switch, vous gardez chaque contexte de travail dans son propre répertoire, prêt à l'emploi.
Les bénéfices principaux :
- Zéro interruption : votre travail en cours reste intact
- Parallélisme : travaillez sur plusieurs tâches simultanément
- Légèreté : pas de duplication du dépôt Git
- Simplicité : quelques commandes suffisent
La prochaine fois que vous devrez gérer un hotfix urgent ou review une PR, pensez à git worktree add — votre futur vous remerciera.
