Qu’est-ce qu’un git worktree ?

En bref

Un git worktree est un dossier de travail supplémentaire rattaché au même dépôt git. Chaque dossier a une branche différente extraite, ce qui permet de travailler sur deux choses à la fois sans recloner le dépôt, et d’éviter que des agents de codage parallèles se marchent sur les pieds.

Comment ça marche

Normalement, un dossier de dépôt a une seule branche extraite, et en changer suppose de committer ou de mettre de côté (stash) d’abord. Avec un worktree, votre dossier principal reste en place et un nouveau dossier, sur une autre branche, est ajouté à côté. Les dossiers partagent l’historique des commits et la base d’objets, mais chacun a son propre HEAD, son index et ses fichiers de travail.

Les commandes de base

Une poignée de commandes couvre l’usage quotidien.

git worktree add ../feature-a -b feature-a : crée une nouvelle branche et un dossier.
git worktree list : affiche les worktrees ouverts.
git worktree remove ../feature-a : supprime le dossier.
git worktree prune : nettoie les enregistrements de dossiers supprimés à la main.

Pourquoi c’est important pour les agents de codage

Deux agents dans le même dossier peuvent s’écraser les fichiers, et le lancement de tests par l’un peut buter sur une modification inachevée de l’autre. Donner à chaque agent son propre worktree l’évite : chacun travaille sur sa branche et vous combinez les résultats par une pull request ou un merge. Des branches qui touchent le même fichier peuvent toutefois entrer en conflit au merge.

Points de vigilance

Les worktrees sont légers, mais quelques détails piègent les utilisateurs.

La même branche ne peut pas être extraite dans deux worktrees à la fois.
Les fichiers non suivis comme node_modules, .env et les sorties de build ne sont pas copiés ; vous devrez peut-être réinstaller les dépendances.
Si chaque worktree lance son propre serveur de développement, surveillez les conflits de ports.
Supprimez les worktrees dont vous avez fini, sinon les dossiers oubliés s’accumulent sur le disque.

Les worktrees dans AgentVera

AgentVera s’appuie sur les worktrees pour faire tourner des agents en parallèle.

Depuis le panneau worktree de Git, ouvrez une branche et un dossier par fonctionnalité et lancez un agent directement dans ce dossier.
Dans la night shift, chaque tâche tourne dans son propre worktree sur une branche night/<date>-<slug> ; l’agent commite mais ne pousse jamais (Pro et Team).
Les environnements de prévisualisation lancent le serveur de développement du projet et de chaque worktree à sa propre adresse, nommée d’après la branche.
La coordination des agents signale quand des agents de worktrees différents modifient le même fichier, car le merge risque d’entrer en conflit.

FAQ

Quelle différence entre un worktree et une branche ?

Une branche est une ligne de commits nommée ; un worktree est un dossier dans lequel une branche est extraite. Avec les seules branches, vous changez dans un même dossier ; avec les worktrees, vous gardez plusieurs branches ouvertes en même temps dans des dossiers séparés.

En quoi un worktree diffère-t-il de deux clones du dépôt ?

Les worktrees partagent un seul dépôt : commits, branches et configuration sont communs, et ils occupent moins d’espace disque. Un commit fait dans un worktree est visible tout de suite depuis les autres, alors que des clones séparés exigent push et fetch.

Comment supprimer un worktree ?

Lancez git worktree remove <dossier>. Si vous avez supprimé le dossier à la main, git worktree prune nettoie l’enregistrement. La branche reste ; supprimez-la séparément avec git branch -d si besoin.

Les worktrees partagent-ils node_modules ?

Non. Les fichiers non suivis sont séparés dans chaque dossier, donc vous installez les dépendances dans chaque worktree.