Git permet depuis longtemps de rattacher plusieurs copies de travail à un même dépôt, chacune sur sa propre branche et dans son propre répertoire. La commande git worktree évite d’empiler des stash pour passer d’une tâche à l’autre et de recloner un projet entier pour ouvrir un simple correctif. Le mécanisme est stable, disponible dans toute version récente de Git, et rend service bien au-delà des très gros dépôts.
Le problème que résolvent les worktrees
Le scénario est courant : une fonctionnalité est en cours, l’arbre de travail est sale, et un correctif urgent tombe sur la branche de production. Les réflexes habituels ont chacun leur coût. Le git stash met le travail de côté mais force à jongler avec une pile invisible, et il ne sépare ni les dépendances installées ni les artefacts de build. Le reclonage complet, lui, duplique tout l’historique et consomme du disque pour un dépôt déjà présent localement.
Un worktree offre une troisième voie : un répertoire supplémentaire, rattaché au dépôt existant, qui porte une autre branche. Le travail en cours reste intact dans son répertoire, le correctif s’ouvre à côté, et les deux cohabitent sans se marcher dessus.
Une branche par répertoire, un seul historique : le changement de contexte ne coûte plus un stash.
Créer, lister, situer un worktree
Un worktree se crée en une commande, à partir d’une branche existante ou en la créant au passage. Le premier argument est le chemin du nouveau répertoire, le second la branche à y placer.
# Ajouter un worktree pour une branche existante
git worktree add ../paiement-hotfix hotfix/paiement
# Créer la branche en même temps que le worktree
git worktree add -b correctif-tva ../correctif-tva main
# Lister les worktrees rattachés au dépôt
git worktree listLe répertoire principal reste le worktree par défaut ; les autres viennent s’y ajouter. git worktree list affiche leur chemin, le commit courant et la branche associée, ce qui donne une vue d’ensemble immédiate des chantiers ouverts.
Ce qui est partagé, ce qui ne l’est pas
Tous les worktrees d’un dépôt partagent un unique répertoire .git : l’historique, les objets, les branches et les remotes sont communs. Un commit réalisé dans un worktree est immédiatement visible depuis les autres, sans push ni fetch. Ce partage est justement ce qui rend l’opération peu coûteuse en disque, comparée à un clone.
En revanche, chaque worktree possède ses propres fichiers de travail, son index et son HEAD. Ce qui vit en dehors du suivi de Git ne suit pas : les dépendances installées (par exemple node_modules), les fichiers d’environnement ignorés et les artefacts de build sont propres à chaque répertoire. C’est un avantage, puisqu’un build lancé dans un worktree n’écrase pas celui d’un autre, mais cela suppose de réinstaller les dépendances dans chaque nouveau répertoire.
| Critère | git stash | Nouveau clone | git worktree |
|---|---|---|---|
| Copies de travail simultanées | Non | Oui | Oui |
| Historique et objets partagés | Oui | Non (dupliqués) | Oui |
| Coût disque | Nul | Élevé | Faible (fichiers de travail seuls) |
| Dépendances et build isolés | Non | Oui | Oui |
| Changement de contexte | Empiler / dépiler | Changer de dossier | Changer de dossier |
Cas d’usage concrets
Le correctif urgent est l’exemple type, mais l’outil sert plusieurs autres routines du quotidien :
- Revue de code : sortir la branche d’une pull request dans un worktree dédié permet de la lancer réellement, de la tester et de la comparer, sans perturber le travail en cours.
- Builds longs : une compilation ou une suite de tests coûteuse peut tourner dans un worktree pendant que le développement continue dans un autre.
- Bisect : isoler une régression avec
git bisectdans un worktree séparé évite de polluer l’arbre de travail principal. - Comparaison de versions : garder deux branches ouvertes côte à côte pour confronter deux implémentations d’une même page ou d’une même API.
Pour un indépendant qui suit plusieurs missions, l’intérêt est net : un dépôt client peut héberger en parallèle la branche de la fonctionnalité facturée et le correctif de production demandé en urgence, sans mélange et sans reclonage.
Détails utiles au quotidien
Quelques points aident à tirer pleinement parti du mécanisme. Dans un worktree secondaire, le .git n’est pas un répertoire mais un simple fichier qui pointe vers le dépôt principal : c’est ce lien qui donne accès à l’historique partagé. La configuration et les hooks vivant dans le dépôt commun, ils s’appliquent à tous les worktrees, ce qui homogénéise les environnements sans copie manuelle.
Trois commandes complètent la panoplie. git worktree add --detach crée un répertoire en état détaché, pratique pour un test jetable sans créer de branche. git worktree move déplace un worktree existant vers un autre chemin. git worktree lock le protège lorsqu’il réside sur un support amovible ou un montage réseau, afin que prune ne le supprime pas pendant une absence. Côté éditeur, la logique est immédiate : chaque worktree s’ouvre comme un dossier de projet indépendant, avec sa propre fenêtre et son propre terminal.
Reste la question de l’emplacement. Placer les worktrees dans un répertoire frère du projet, voire dans un dossier dédié regroupant les copies d’un même dépôt, garde l’arborescence lisible et évite d’imbriquer un worktree dans un autre. Comme les remotes sont partagés, un git fetch lancé depuis n’importe quel worktree met à jour les références pour tous, ce qui évite de multiplier les allers-retours réseau. Cette économie, invisible sur un petit projet, devient tangible sur un dépôt lourd où chaque clone supplémentaire se paierait en minutes et en gigaoctets.
Nettoyer et éviter les pièges
Une fois la branche fusionnée, le worktree se retire proprement. Supprimer le répertoire à la main laisse des références orphelines que git worktree prune nettoie.
# Retirer un worktree une fois la branche fusionnée
git worktree remove ../paiement-hotfix
# Nettoyer les références aux worktrees supprimés à la main
git worktree pruneTrois pièges à connaître. Une même branche ne peut pas être extraite dans deux worktrees à la fois : Git le refuse pour éviter deux historiques divergents sur la même référence. Les dépendances et les fichiers ignorés ne sont pas partagés, il faut les réinstaller dans chaque répertoire. Enfin, les chemins relatifs et les scripts qui supposent une racine de projet fixe peuvent surprendre si le worktree vit ailleurs dans l’arborescence.
Ce qu’il faut retenir
Les worktrees remplacent avantageusement le duo stash plus reclonage dès qu’il faut tenir deux contextes ouverts en même temps. Ils partagent l’historique pour rester légers, isolent les fichiers de travail pour éviter les collisions, et se manipulent avec trois commandes : add, list, remove. L’habitude à prendre est de nettoyer les répertoires terminés, pour ne pas laisser traîner des copies de travail oubliées.
Sur mes missions freelance, les worktrees ont réglé le cas le plus pénible : un correctif de prod qui tombe en plein milieu d’une feature à moitié écrite. Plus de stash à retrouver trois jours plus tard, plus de node_modules à recompiler dans le mauvais sens. Un répertoire par contexte, et l’esprit reste clair. Le seul réflexe à installer, c’est le remove : sans lui, on accumule des worktrees fantômes qu’on finit par ne plus oser toucher — Simon Janvier
Pour aller plus loin
Git — Documentation officielle de git-worktree
