Un worktree par agent

À quoi sert un worktree

Un worktree git est un second dossier de travail du même dépôt, sur sa propre branche. Avec l’option « Un worktree par agent », chaque nouvel agent reçoit le sien : ses modifications restent à part, ni les autres agents ni ton propre dossier ne les voient tant que tu ne les as pas mergées, et le panneau des fichiers les liste séparément (voir Git).

Sans worktree, tous les agents d’un projet travaillent dans le dossier du projet et leurs modifications se mélangent : Escouade les attribue alors à chaque agent d’après ses éditions.

Les agents des tickets du Kanban travaillent toujours dans un worktree à eux, sur la branche de leur ticket, que l’option soit activée ou non. Ils suivent les mêmes réglages de dossier, de fichiers copiés et de commandes que les autres.

L’activer

L’option se règle par projet, et ne concerne que les agents créés ensuite : ceux qui existent déjà restent où ils sont. Trois endroits la proposent :

• la fenêtre « Nouveau projet », avec l’interrupteur « Un worktree git par agent » (désactivé par défaut) ;
• un clic droit sur l’onglet du projet, puis « Activer le worktree par agent » ou « Désactiver le worktree par agent » (l’entrée précise « nouveaux agents ») ;
• Réglages › Projets, groupe « Git », « Un worktree par agent ».

Le dossier du projet doit être sur une branche qui a au moins un commit : un dépôt neuf, sans aucun commit, ne peut pas encore avoir de worktree. Quand un worktree ne peut pas être créé, l’agent travaille dans le dossier du projet et la conversation affiche « Worktree non créé, l’agent travaille dans le dossier du projet : … » avec la raison.

Où il va et comment il s’appelle

Quatre réglages du projet décident de l’emplacement et des noms (Réglages › Projets, groupe « Git »). La liste complète des réglages est dans les réglages des projets.

Le dossier du worktree est <dossier des worktrees>/<nom de l’agent>, sur une branche nouvelle <préfixe><nom de l’agent>. Si l’un des deux existe déjà, Escouade ajoute -2, -3… Un agent s’appelle d’abord agent-1, agent-2… ; quand Escouade le nomme d’après son premier message (par exemple refacto-auth), sa branche devient escouade/refacto-auth si ce nom est libre, alors que le dossier garde son premier nom. Un nom que tu donnes toi-même ne change jamais la branche. La carte de l’agent montre la branche sans son préfixe (⎇ refacto-auth), et son nom entier s’affiche au survol.

Le worktree part du commit où se trouve le dossier du projet à ce moment-là. La branche de ce dossier devient la branche de base de l’agent : c’est elle que le merge et « Intégrer » visent.

Quand le dossier des worktrees est dans le dépôt (le cas par défaut), Escouade l’ajoute au fichier .git/info/exclude du dépôt : les worktrees n’apparaissent pas dans les changements du projet. Un dossier qui contient déjà des fichiers suivis par git est refusé : « Le dossier des worktrees … contient des fichiers suivis par git : choisis-en un autre dans les réglages du projet. »

Les fichiers copiés

Un fichier comme .env, que git ignore, n’existe pas dans un worktree neuf. Juste après la création du worktree, Escouade y copie les fichiers du projet qui sont ignorés par git et qui correspondent à un motif du réglage « Fichiers copiés dans les worktrees ».

• Un motif par ligne, avec * et ? dans un nom et ** pour traverser des dossiers : .env* prend les fichiers de la racine, **/.env* ceux de tous les dossiers. Par défaut, .env*.
• Seuls les fichiers ignorés par git sont copiés, donc aucun ne peut finir dans un commit. Un fichier suivi par git n’est jamais copié.
• Les copies apparaissent dans l’arborescence de l’éditeur, en grisé (« Ignoré par git »). Le commit direct ne les prend jamais.
• Si une copie échoue, la conversation le dit (« Fichiers non copiés dans le worktree : … ») et l’agent travaille sans ce fichier.

Préparer le worktree

Un worktree neuf n’a ni dépendances installées ni code généré. Le groupe « Worktrees » des réglages du projet liste les commandes que lance Escouade pour le préparer, dans la liste « À l’ouverture d’un worktree » : elles tournent dans l’ordre, dans le nouveau worktree, avant le premier message de l’agent, et ses messages attendent la fin.

Chaque commande a un shell (le premier shell détecté par défaut), une ligne de commande (par exemple npm ci) et un « Sous-dossier » du worktree (vide, c’est sa racine). « + Ajouter une commande » en ajoute une, la croix la supprime. Pour changer l’ordre, utilise les boutons ↑ et ↓ de la commande, ou Alt+↑ et Alt+↓ (⌥↑ et ⌥↓ sous macOS) depuis n’importe quel champ de la commande. Une commande vide est ignorée.

Les commandes reçoivent ces variables d’environnement :

Le proxy du réglage « Proxy HTTP(S) » est transmis aux commandes quand « Appliquer aussi le proxy aux terminaux intégrés » est activé (voir les réglages du réseau). Une commande qui dépasse 20 minutes est arrêtée.

Suivre la préparation

• La carte de l’agent dit « Préparation… » ; son info-bulle donne la commande en cours.
• La conversation affiche « Préparation du worktree · npm ci — tes messages partiront une fois terminée. » Le bouton « Voir la sortie » déplie les dernières lignes de ce que la commande écrit, en direct. La sortie suit les nouvelles lignes tant que tu es en bas, et reste en place si tu remontes.
• Un message que tu envoies pendant la préparation attend : il part une fois la préparation finie.
• À la fin, la conversation note « Worktree préparé (3 commandes, 12 s). »
• La sortie complète de la dernière préparation, commande après commande, est écrite dans ~/.escouade/logs/, un fichier par agent nommé <identifiant de l’agent>-setup.log. Il est remplacé à chaque préparation et supprimé avec l’agent.

Archiver ou supprimer l’agent pendant sa préparation l’arrête.

Quand une commande échoue

La première commande qui échoue arrête la préparation : les suivantes ne tournent pas. La conversation affiche un avertissement, par exemple « La préparation du worktree a échoué sur npm ci (code 1). », suivi des 30 dernières lignes de la sortie et du chemin de la sortie complète (« Sortie complète : … »). L’échec peut aussi venir d’un sous-dossier qui n’existe pas dans le worktree, d’une commande qui ne démarre pas ou d’une commande arrêtée après 20 minutes.

L’agent est prévenu dans son premier message, avec la commande qui a échoué et ses dernières lignes, et il démarre quand même : il peut en tenir compte.

Remplir automatiquement

« ✦ Remplir automatiquement », en haut du groupe « Worktrees », demande à Claude de lire le projet (manifestes, lockfiles, README…) et de proposer les commandes. Il ne modifie rien : il n’a que des outils de lecture, et il dispose de 4 minutes au plus. Sa proposition s’affiche à part, sous « Commandes de worktree proposées », avec chaque commande en entier, son shell et son dossier :

• « Remplacer les commandes » remplace les deux listes du brouillon (préparation et démontage). Rien n’est gardé tant que tu n’as pas cliqué « Enregistrer » dans la fenêtre des réglages ;
• « Ignorer » abandonne la proposition.

Claude propose huit commandes au plus par liste. Une commande sur plusieurs lignes, avec des caractères invisibles, avec une suite de 24 espaces ou plus, ou de plus de 300 caractères est écartée, et le message qui suit la lecture le dit (« 2 commandes proposées, 1 écartée (caractères invisibles ou trop longue) : relis-les avant d’enregistrer. »).

Démonter le worktree

La liste « Avant sa suppression » contient ce qu’il faut défaire hors du worktree avant de le supprimer : une base de données ou des conteneurs que la préparation a créés pour lui. Le plus souvent, elle est vide. Elle s’édite comme celle de la préparation, et se remplit aussi avec « ✦ Remplir automatiquement ».

Ces commandes tournent quand un agent est supprimé avec son worktree, et quand le Kanban nettoie le worktree d’un ticket. Chacune tourne même si la précédente a échoué, avec 5 minutes au plus, et leur sortie n’est pas affichée. Si le projet utilise isola (un fichier .isola.toml), isola destroy passe ensuite. Un problème est signalé une fois l’agent supprimé : « Agent supprimé, mais le démontage du worktree a échoué sur … ».

Travailler sur une branche qui existe déjà

Un agent peut aussi travailler dans un worktree sur une branche qui existe déjà, au lieu d’en créer une nouvelle :

• « Nouvel agent sur une branche… » dans le menu du bouton ▾, à droite de « Nouvel agent », ouvre le sélecteur de branches (« Choisir une branche ») ;
• dans le sélecteur de branches de la barre d’état, un clic droit sur une branche propose « Lancer un agent sur cette branche » ;
• dans le formulaire d’un ticket, le champ « Branche » propose « Reprendre une branche existante… ».

Une branche distante est reprise par la branche locale qui la suit, créée si elle n’existe pas. Le dossier du projet n’est pas touché. Trois branches sont refusées, avec la raison : celle du dossier du projet, la branche cible du Kanban (les tickets y sont mergés) et celle qu’un autre worktree occupe déjà.

Cette branche est celle de l’agent, mais elle n’est jamais créée ni supprimée par Escouade : en supprimant l’agent, la case propose « Supprimer aussi le worktree (la branche … est conservée) ». Sa branche de base est la branche cible du Kanban si elle existe, sinon la branche du dossier du projet. Pour un ticket, l’infobulle de l’entrée dit « Escouade ne supprime jamais cette branche, même une fois le ticket validé. » Les branches sont détaillées dans la page des branches.

Fusionner dans la branche de base

Quand le travail d’un agent te convient, tu le fusionnes dans sa branche de base depuis le panneau des fichiers :

1. L’agent doit avoir commité son travail (voir Git). Le merge ne prend que des commits.
2. Dans le panneau, onglet « Non commités », bouton « Cet agent », clique « Merger escouade/refacto-auth → main… ».
3. La fenêtre demande « Merger escouade/refacto-auth dans main ? » et précise que les commits de l’agent sont intégrés dans la branche « main » du projet. La case « Squash (un seul commit) » est décochée par défaut. Clique « Merger ».

Le merge se fait dans le dossier du projet.

Escouade refuse le merge, avec un message, dans ces cas :

• l’agent a des fichiers non commités (« L’agent a 2 fichiers non commités : demande-lui de commiter avant de merger. ») ;
• le dossier du projet a des modifications non commitées sur des fichiers suivis : commite-les ou mets-les de côté ;
• la branche de l’agent n’a aucun nouveau commit (« Rien à merger ») ;
• la branche de base n’existe plus.

Si le dossier du projet n’est pas sur la branche de base, une question s’affiche : « Basculer sur « main » ? » Elle dit sur quelle branche est le projet. « Basculer et merger » bascule le dossier sur la base, puis merge.

Un merge qui a des conflits est annulé : le dossier du projet reste comme avant et un message d’erreur s’affiche. Dans ce cas, fais d’abord entrer la base dans la branche de l’agent avec « Intégrer main », qui confie les conflits à l’agent (voir les branches), puis recommence.

Le merge ne supprime ni le worktree ni la branche de l’agent. Pour les ranger, supprime l’agent avec son worktree (voir ci-dessous) ; pour nettoyer d’un coup les branches déjà mergées, utilise « Branches mergées » dans le sélecteur de branches. Pour les tickets du Kanban, la validation se charge du commit, du merge ou de la pull request selon les réglages (voir les réglages du Kanban).

Archiver, restaurer, supprimer

Les actions sont dans le menu d’un clic droit sur la carte de l’agent.

• « Archiver » arrête l’agent et garde sa conversation. Son worktree et sa branche restent sur le disque. La confirmation n’apparaît que pour un agent dont le ticket est en cours ou à tester.
• « Restaurer » ramène un agent archivé. Si son dossier de worktree a disparu entre-temps, par exemple après une pull request ou un push, Escouade le recrée à partir de sa branche, recopie les fichiers du projet et relance la préparation. Si un autre worktree a pris son dossier, le sien est recréé à côté (-2) et la conversation l’indique. Si la branche n’existe plus (mergée puis supprimée), l’agent reste tel quel.
• « Supprimer… » demande confirmation. La case « Supprimer aussi le worktree et la branche escouade/refacto-auth » est cochée par défaut. Cochée, Escouade arrête l’agent, lance les commandes de démontage, supprime le dossier du worktree puis la branche. Décochée, l’agent disparaît d’Escouade et le worktree et la branche restent sur le disque. Si des fichiers de ce worktree sont ouverts et non enregistrés dans l’éditeur, la fenêtre prévient qu’ils seront perdus.

Si le nettoyage rencontre un problème (un processus qui tient encore le dossier, un démontage qui échoue), l’agent est supprimé quand même et un message le signale après coup. Fermer un projet ne touche pas à ses worktrees sur le disque.

Dupliquer un agent

« Dupliquer la conversation » (menu de l’agent) copie un agent qui a un worktree dans un worktree à lui, créé à partir du commit où se trouve l’original, sur une nouvelle branche dont le nom reprend celui de la copie. Les modifications non commitées de l’original n’y sont pas, et la conversation le dit. Voir les agents.