Branches et revue

Une session de branche est une session qui travaille sur sa propre branche git, dans son propre checkout du dossier d'où elle vient. Sous le capot, c'est un worktree git : une deuxième copie de travail du même dépôt, partageant son historique mais avec ses propres fichiers et son propre index. Votre travail dans la session d'origine n'est pas touché. Quand la branche est prête, vous la fusionnez depuis la session elle-même.

Utilisez une branche pour essayer une idée à côté de la ligne de travail principale, pour découper une tâche entre plusieurs agents qui ne se marcheront pas sur les fichiers non validés, ou pour laisser un agent explorer quelque chose que vous jetterez peut-être.

Ce chapitre couvre aussi la fenêtre de revue, qui fonctionne pour toute session ayant un dossier, branche ou non.

Démarrer une branche

Branchez n'importe quelle session qui a un dossier :

• clic droit dans la barre latérale et Nouvelle branche…
• Nouvelle branche… dans le menu ⋯ de l'en-tête de session
• Nouvelle branche… dans la palette ⌘K, qui agit sur la session sur la scène

La feuille Nouvelle branche indique « Une session à elle, sur une copie de dossier avec sa propre branche git. Votre travail dans « session » n'est pas touché ; fusionnez-la quand elle est prête. » Elle comporte ces parties :

• Partir de (branche actuelle) : « À son dernier commit — les modifications non validées restent en arrière. Fusionne dedans. »
• Partir de (une autre branche) : « Au dernier commit de branche, et elle fusionne dans branche. » La branche de départ est aussi celle dans laquelle la session fusionne.

Sous les champs, la feuille montre la branche qu'elle va créer, wt/<nom>. Le nom est mis en minuscules, les autres caractères devenant des tirets. Cliquez Démarrer (⌘⏎).

Note : seul le travail validé est branché. Les modifications non validées dans le dossier d'origine y restent et ne sont pas copiées dans le nouveau checkout.

Ce que la feuille vérifie d'abord

La feuille demande à la machine ce qu'est le dossier (« Vérification de dossier… ») et s'adapte :

• Un dépôt : le sélecteur Partir de décrit ci-dessus. Si le dépôt a un fichier .worktreeinclude, la feuille ajoute « Copie aussi, comme l'indique .worktreeinclude : … » suivi des fichiers qu'il liste. Ce sont des fichiers que git ne suit pas, comme un .env local, copiés dans le nouveau checkout.
• Un dépôt sans aucun commit : « Le dépôt n'a pas encore de commit, la branche part donc d'un premier commit vide. Les fichiers du dossier restent en arrière. »
• Pas un dépôt : « dossier n'est pas encore un dépôt git, et une branche en exige un. » Cochez En faire un (git init) pour y lancer git init. « Tout ce qui est dans le dossier entre dans un premier commit, dont part la branche. » Démarrer est désactivé si cette case n'est pas cochée.
• La machine ne tourne pas : « La machine ne tourne pas — le dossier est vérifié dès qu'elle démarre. » L'option Si ce n'est pas un dépôt git, en faire un s'applique au démarrage de la machine.

Astuce : les agents peuvent aussi démarrer des branches, avec l'outil worktree_create du serveur MCP bromure-delegation. Une telle branche apparaît exactement comme une que vous auriez démarrée. Voir Des agents qui travaillent ensemble.

Une session de branche

Une session de branche est imbriquée sous la session d'où elle vient dans la barre latérale. Sa ligne ajoute un glyphe de branche et une ligne d'état comme « 3 commits ». La ligne d'état compte :

• les commits d'avance sur la branche d'origine (« 1 commit », « n commits »)
• les fichiers non validés (« n fichiers non validés »)
• les commits de retard (« n de retard »)

Elle indique « aucune modification pour l'instant » jusqu'au premier changement. Les décomptes sont lus sur la machine environ toutes les 20 secondes tant qu'elle tourne.

Dans l'en-tête de session, à côté du dossier, une puce montre le nom de la branche et les mêmes décomptes. Survolez-la pour lire « Sa propre branche git, issue de parent — fusionnez-la quand elle est prête ».

Fusionner

Dès que la branche a des modifications, l'en-tête montre un bouton fractionné, Fusionner dans parent.

Cliquez la partie principale pour fusionner la branche dans celle d'où elle vient. Le checkout et la branche sont alors supprimés, et la session est archivée. La session reste lisible, avec une ligne d'état « Fusionnée dans parent ».

La partie fléchée ouvre les autres options, qui se trouvent aussi dans la section Branche des menus ⋯ et contextuel de la session :

Une fusion se déroule ainsi :

1. Une branche propre fusionne aussitôt. Pendant l'opération, l'en-tête indique « Fusion dans parent… ».
2. Du travail non validé ou un conflit passe à l'agent. Quand la branche a des fichiers non validés, ou que la fusion entre en conflit, Bromure annule la fusion et laisse tout propre. Il demande alors à l'agent de la session, dans sa conversation, de valider le travail, de fusionner et de résoudre les éventuels conflits. L'en-tête indique « Fusion dans parent — l'agent la termine », et vous pouvez suivre dans le chat. Si git n'a pas d'identité sur la machine, le commit de fusion est fait au nom de Bromure <bromure@localhost>.
3. Bromure vérifie que la fusion a bien atterri avant de supprimer quoi que ce soit. Si elle n'a pas atterri après 30 minutes, l'état devient Fusion bloquée : « La fusion n'a pas abouti après 30 minutes — demandez à l'agent où il en est. » Le bouton indique alors Relancer la fusion.

Une fusion en cours au moment où vous quittez est reprise au lancement suivant.

Quand un agent demande à fusionner

Un agent peut demander à fusionner une branche avec l'outil worktree_merge. Il peut demander pour sa propre branche, ou pour une branche démarrée depuis sa session. Il ne fusionne jamais de lui-même. Une bannière apparaît sous l'en-tête de la session : « Agent demande à fusionner branche dans cible ». La ligne en dessous donne les décomptes de la branche, « En un seul commit squashé » si l'agent a demandé un squash, et « Le checkout est supprimé dès que la fusion a abouti. »

• Examiner les modifications ouvre la fenêtre de revue.
• Plus tard refuse. Il est dit à l'agent de ne plus demander à moins que vous n'en reparliez.
• Fusionner (ou Squash et fusionner) lance la fusion comme décrit ci-dessus. Quand elle aboutit, l'agent qui a demandé en est informé.

Archiver ou supprimer une session de branche

Archiver ou supprimer une session de branche dont le travail n'est pas fusionné demande ce qu'il advient de la branche : « Archiver « session » — et sa branche ? » ou « Supprimer « session » — et sa branche ? ».

• Conserver la branche laisse le checkout et la branche sur la machine, pour que vous puissiez la fusionner ou la reprendre plus tard. La machine ne la réouvre plus au démarrage. Reprendre la session la réouvre.
• Abandonner la branche supprime le checkout et la branche avec la session. « branche a du travail non fusionné (…) » vous dit ce que vous perdriez.

Si rien n'a été fait sur la branche (« Rien n'a encore été fait sur branche, il n'y a donc rien à perdre à la supprimer. »), Abandonner la branche est le choix par défaut.

Abandonner explicitement, avec Abandonner la branche…, demande toujours confirmation d'abord : « Abandonner « session » ? La branche branche et son checkout sont supprimés avec la session. C'est irréversible. »

Les branches sur une machine

Les branches sont faciles à perdre de vue dès que leur session est archivée, fusionnée ou disparue. Branches sur cette machine… ouvre une fenêtre listant toutes les branches que Bromure a créées sur une machine. Vous la trouvez dans le menu ⋯ de l'en-tête de session et par un clic droit sur la capsule de la machine dans l'en-tête.

La fenêtre, intitulée « Branches sur machine », compte « n branches · n laissées derrière ». Chaque ligne montre :

• le nom de la branche, et à qui elle est : Dans une session, Session en pause, Session archivée, Fusionnée, ou Aucune session
• la branche, une flèche, et la branche dans laquelle elle fusionne
• ce qu'elle contient, et la date de son dernier commit
• le chemin de son checkout sur la machine

Les actions de ligne dépendent de qui possède la branche :

• Examiner et Afficher la session pour une branche qui a une session.
• Ouvrir dans une session pour une branche qui n'en a pas. Cela démarre l'agent par défaut de la machine dans le checkout de la branche. La nouvelle session est une véritable session de branche : fusion, revue et abandon fonctionnent tous.
• Le bouton corbeille, « Abandonner la branche et son checkout », demande d'abord. Si la branche a une session archivée, cette session est supprimée aussi.

Seulement sans session réduit la liste aux branches laissées derrière. ⌘R actualise. Les branches sont lues en direct sur la machine, qui doit donc tourner : « Les branches sont lues en direct sur la machine — démarrez-la et actualisez. »

La fenêtre de revue

La fenêtre de revue montre les modifications d'une session sous forme de diff et vous permet de les commenter. Elle n'est pas réservée aux branches. Il y a trois façons de l'ouvrir :

• Examiner les modifications, depuis le menu ⋯ de la session, les menus Branche, la palette ⌘K, ou la bannière de demande de fusion.
• La ligne … fichiers modifiés sous une réponse de l'agent dans le chat. La fenêtre s'ouvre alors sur les seuls fichiers que ce tour a modifiés (« Modifiés dans ce tour »). Cliquez Tout afficher pour voir l'ensemble, et Ce tour pour restreindre à nouveau.
• Examiner dans la fenêtre des branches.

La fenêtre est intitulée « Revue — session ». Ses parties :

• Le sélecteur de comparaison (« À quoi les modifications sont comparées ») :
  • Depuis parent n'existe que pour les sessions de branche, et c'est leur défaut. Il montre tout ce que la branche a et que son parent n'a pas.
  • Non validé montre les modifications pas encore validées. C'est le défaut pour les autres sessions.
  • Dernier commit montre le commit le plus récent.
• La liste des fichiers montre combien de fichiers ont changé, « n sur n vus » avec une barre de progression, et les commits de la branche. Les nouveaux fichiers que git ne suit pas encore sont inclus et comptés (« n nouveaux fichiers pas encore ajoutés à git »). Cliquez un fichier pour y sauter.
• Marquer comme vu. Le cercle à côté de chaque fichier le marque comme regardé, et il se replie. La marque est liée au diff actuel du fichier : elle revient si le fichier change encore.
• Le diff. Survolez une ligne pour la commenter. Vous pouvez aussi commenter un fichier entier (« Un commentaire sur ce fichier ») ou, dans le champ en bas, toute la modification.
• L'en-tête a un bouton Actualiser (⌘R) et Ouvrir le terminal, plus le bouton de fusion pour une session de branche.

Commentaires

Un commentaire que vous ajoutez (⏎) est un brouillon : « il attend avec les autres jusqu'à ce que vous les envoyiez ». ⌥⏎ ajoute une nouvelle ligne. Le × supprime un brouillon.

Envoyer n commentaires à l'agent (⇧⌘⏎) envoie tous les brouillons à l'agent de la session en un seul message numéroté, chaque commentaire avec son fichier et sa ligne, et demande à l'agent de les traiter. Si l'agent ne tourne pas, le message le reprend. Les commentaires envoyés restent dans la fenêtre, marqués « envoyé ». Les commentaires et les marques de lecture sont enregistrés avec la session et survivent à la fermeture de la fenêtre.

Les modifications sont lues en direct sur la machine. Si elle est éteinte, la fenêtre indique « Impossible d'atteindre la machine » : démarrez la machine et actualisez.

Note : les tâches de code utilisent la même fenêtre de revue, avec des boutons propres aux tâches comme Renvoyer avec n commentaires.

Les terminaux de machine

Les onglets du terminal Linux d'une machine gardent les anciennes actions de worktree : Nouveau worktree (⇧⌘G), Fusionner le worktree (⇧⌘M) et Attacher un terminal, dans le menu Espaces de travail. Voir Machines. Pour les sessions d'agent, les actions de branche ci-dessus les remplacent.

Sur un serveur en miroir et sur iOS

Les sessions de branche, la fusion, la bannière de demande de fusion, la fenêtre de revue et la fenêtre des branches fonctionnent toutes dans une fenêtre de client lourd en miroir d'un autre Mac. Les clients iPhone et iPad proposent Nouveau worktree… dans le menu d'appui long d'une session, qui ouvre la même feuille de branche. Là où leur menu de branche apparaît, Abandonner la branche… ouvre un sous-menu, Abandonner — c'est irréversible, à la place du dialogue de confirmation.