git worktree

Ce que fait git worktree

La commande git worktree vous permet d'extraire plus d'une branche en même temps depuis un seul dépôt. Chaque worktree est un répertoire de travail distinct avec sa propre branche extraite et son propre index, mais ils partagent tous le même magasin d'objets .git, l'historique, les références et la configuration. C'est la façon propre de travailler sur deux branches en parallèle sans cloner le dépôt deux fois.

Le répertoire dans lequel vous avez cloné est votre worktree principal ; chaque répertoire créé avec git worktree add est un worktree lié. Les worktrees liés sont légers : ils ne stockent qu'un petit fichier .git (pas un dossier) qui pointe vers le dépôt partagé, ce qui leur coûte presque rien sur le disque par rapport à un second clone.

Cette page explique quand utiliser un worktree, comment en ajouter, lister, déplacer et supprimer, les règles imposées par Git, et les pièges courants.

Le problème qu'il résout

Imaginez que vous êtes en plein milieu d'une branche de fonctionnalité quand un rapport de bogue urgent arrive. Normalement, vous devriez remiser votre travail, changer de branche, corriger le bogue, revenir en arrière et désempiler — une opération perturbatrice et sujette aux erreurs. Avec les worktrees, vous créez simplement un second répertoire de travail extrait sur la branche de correctif, corrigez le bogue là-bas, et laissez votre travail de fonctionnalité complètement intact. Quand la construction nécessite les deux états côte à côte — par exemple pour comparer un comportement ou exécuter deux longues suites de tests en même temps — les worktrees brillent là où le remisage ne peut pas aider.

Ajouter un worktree

Pointez git worktree add vers un chemin et une branche. Pour extraire une branche existante dans un répertoire voisin :

git worktree add ../hotfix hotfix

Cela crée ../hotfix avec la branche hotfix extraite :

Preparing worktree (checking out 'hotfix')
HEAD is now at 1a2b3c4 Add login form

Pour créer une toute nouvelle branche en même temps, utilisez -b. Le dernier argument est le point de départ sur lequel la nouvelle branche est basée :

git worktree add -b experiment ../experiment main

Vous avez maintenant deux répertoires de travail indépendants soutenus par un seul dépôt. Si vous omettez la branche entièrement, Git crée une branche nommée d'après le dernier composant du chemin :

git worktree add ../docs    # creates and checks out a branch named "docs"

Pour inspecter un commit sans y placer une branche — pratique pour tester une ancienne version — ajoutez-le en état HEAD détaché :

git worktree add --detach ../v1-check v1.0.0

Consultez Detached HEAD pour comprendre ce que signifie cet état.

Lister les worktrees

Affichez tous les arbres de travail attachés au dépôt :

git worktree list

La sortie montre chaque chemin, le commit sur lequel il se trouve, et la branche (ou (detached HEAD)) :

/home/dev/project          1a2b3c4 [main]
/home/dev/hotfix           9f8e7d6 [hotfix]
/home/dev/v1-check         0011223 (detached HEAD)

Ajoutez --porcelain pour un format stable et adapté aux scripts.

Déplacer et supprimer des worktrees

Pour déplacer un worktree lié, laissez Git mettre à jour ses données administratives à votre place plutôt que d'utiliser mv depuis le shell :

git worktree move ../hotfix ../urgent-fix

Quand vous avez terminé avec l'un d'eux, supprimez-le (cela efface son répertoire) :

git worktree remove ../urgent-fix

Git refuse de supprimer un worktree qui contient des modifications non validées ou des fichiers non suivis, ce qui vous protège contre une perte de travail accidentelle. Une fois que vous êtes sûr, outrepassez cette vérification avec --force :

git worktree remove --force ../urgent-fix

Si vous avez supprimé manuellement le dossier d'un worktree avec rm -rf, le dépôt conserve encore un enregistrement administratif obsolète. Nettoyez-le avec :

git worktree prune

Verrouiller un worktree

Si un worktree réside sur un disque amovible ou un partage réseau, verrouillez-le pour que prune ne supprime jamais ses données administratives quand le disque est démonté :

git worktree lock ../usb-backup --reason "external disk"
git worktree unlock ../usb-backup

Récapitulatif des commandes

Règles et pièges

• Une branche, un worktree. Une branche ne peut être extraite que dans un seul worktree à la fois. Si vous tentez d'ajouter un worktree pour une branche déjà extraite ailleurs, Git refuse avec fatal: '<branch>' is already used by worktree at .... Cela garantit que deux répertoires ne peuvent jamais se disputer le même pointeur de branche. Utilisez --detach, ou une nouvelle branche avec -b, si vous avez besoin du même commit en deux endroits.
• Les modifications locales ne sont pas partagées. Chaque worktree possède ses propres fichiers de travail, son index et sa remise. Les commits, branches, tags et remotes sont partagés car ils résident dans le magasin .git commun.
• Supprimer le worktree principal. Vous ne pouvez pas faire git worktree remove sur le worktree original (principal) — seulement sur les worktrees liés.
• Les dépôts nus sont un excellent hôte pour les worktrees : clonez avec git clone --bare, puis ajoutez chaque branche de travail comme son propre worktree, en gardant les données du dépôt séparées de toute extraction.

Commandes associées

• git branch — créer et gérer les branches que vous extrayez dans les worktrees.
• git switch — se déplacer entre les branches dans un seul répertoire de travail.
• git stash — l'ancienne alternative à répertoire unique pour un worktree rapide.

Pratique