Worktrees

Les worktrees Git donnent aux tâches parallèles leurs propres fichiers suivis et branches dans Paneflow. Chaque checkout peut avoir ses panneaux et sessions d'agent, tandis que l'historique du dépôt reste partagé sur votre machine. Cela ne supprime pas les conflits de fusion et n'isole pas les programmes en cours d'exécution.

Paneflow crée et supprime les worktrees gérés. Avant suppression, il fait un snapshot des fichiers non commités sur disque ; sauvegardez d'abord les buffers de l'éditeur. Les fichiers ignorés et secrets locaux demandent un traitement distinct, décrit plus bas.

Ce qu'est un worktree

Les worktrees n'existent que pour les projets qui vivent dans un dépôt Git, parce que Paneflow utilise les worktrees Git sous le capot. Un worktree est une seconde copie (« checkout ») de votre dépôt. Il possède sa propre copie de chaque fichier, mais partage les mêmes métadonnées (le dossier .git) sur les commits, les branches et les remotes. C'est ce qui permet de checkouter et de travailler sur plusieurs branches en même temps.

Terminologie

• Checkout du projet : le dépôt que vous avez ouvert comme espace de travail, celui vers lequel pointe votre dossier de projet.
• Worktree géré : un worktree Git que Paneflow a créé depuis ce checkout, et qu'il nettoie pour vous.
• Snapshot : un commit que Paneflow fait des fichiers non committés sur disque juste avant de supprimer le worktree. Les buffers non enregistrés et les fichiers ignorés ne sont pas couverts par cette garantie.

Pourquoi utiliser un worktree

• Laisser un agent travailler sur une fonctionnalité pendant qu'un autre corrige un bug, chacun sur sa branche, sans toucher au checkout du projet.
• Garder une tâche longue en arrière-plan pendant que vous restez concentré sur le premier plan.
• Lire le diff dans l'onglet Changes de la session, sans toucher au checkout du projet.

Premiers pas

Les worktrees exigent un dépôt Git. Vérifiez que le projet ouvert en fait partie.

Ouvrir un pane sur une nouvelle branche

1. Ajoutez un pane. La palette « New pane » s'ouvre avec une ligne de branche au-dessus de la liste des agents.
2. Ouvrez la ligne de branche et choisissez New branch….
3. Tapez un nom de branche, ou laissez-le vide pour démarrer en détaché.
4. Choisissez la branche ou le commit de départ dans from. Par défaut, c'est la branche sur laquelle est votre projet.
5. Laissez le toggle Worktree activé.
6. Choisissez avec quoi ouvrir : un terminal, Claude Code, Codex, OpenCode ou n'importe quel lanceur que vous avez configuré.

Paneflow crée la branche et son worktree depuis la base choisie, lie l'onglet à ce worktree et y ouvre le pane. L'onglet affiche le nom de la branche, et l'agent démarre dans le dossier du worktree.

Le même flux existe à deux autres endroits :

• Le menu contextuel de l'onglet propose New branch… pour un onglet déjà existant.
• paneflow up et les flows acceptent les champs worktree et from ; voir Scripting.

Réutiliser une branche qui existe déjà

Choisissez une branche existante dans la ligne de branche, ou tapez son nom dans « New branch… ». Si la branche est déjà checkoutée dans un worktree, Paneflow réutilise ce worktree. Si elle n'est checkoutée nulle part, Paneflow lui crée un worktree. La base « from » est alors ignorée, puisque la branche a déjà son propre historique.

Git n'autorise le checkout d'une branche qu'à un seul endroit à la fois. Paneflow ne lutte jamais contre cette règle : il réutilise le checkout existant au lieu d'échouer avec 'feature/a' is already used by worktree at ….

Démarrer en détaché, nommer la branche plus tard

Laissez le nom de branche vide et Paneflow crée un worktree détaché à la base choisie, nommé <base>-<sha> d'après le commit de départ. C'est le bon choix quand vous ne savez pas encore si le travail mérite une branche.

Quand c'est le cas, faites un clic droit sur l'onglet et choisissez Create branch here…. Paneflow lance git switch -c dans ce worktree, donc vos modifications non commitées restent exactement où elles sont.

Basculer le checkout du projet à la place

Désactivez le toggle Worktree dans le formulaire « New branch… » et Paneflow bascule votre checkout du projet sur la branche, sur place, comme le ferait git switch -c, au lieu de créer un worktree. Le pane s'ouvre à la racine du dépôt, et rien n'est ajouté à la liste des worktrees gérés.

Utilisez-le quand vous travaillez seul sur le dépôt et voulez une branche sans second dossier. Paneflow mémorise votre dernier choix dans worktrees.for_new_branches, le toggle s'ouvre donc comme vous l'avez laissé.

Basculer un checkout déplace les fichiers sous tous les panes qui l'utilisent, donc Paneflow refuse la bascule tant qu'un agent travaille dans ce checkout. Un worktree existe exactement pour ce cas.

Où vivent les worktrees

Paneflow crée les worktrees gérés sous ~/.paneflow/worktrees (%USERPROFILE%\.paneflow\worktrees sur Windows), un sous-dossier par dépôt et un dossier par branche :

~/.paneflow/worktrees/
  paneflow-05926cc4/
    feat-agents-browser/
    fix-login/

Rien n'est écrit dans le checkout lui-même. Le marqueur qui indique à Paneflow qu'il possède un worktree vit dans les métadonnées Git propres au worktree, donc git status reste propre et le marqueur disparaît avec le worktree.

Changez la racine dans Settings > Worktrees, ou définissez worktrees.dir dans paneflow.json. La nouvelle racine s'applique aux worktrees créés ensuite ; ceux créés sous une racine précédente continuent de fonctionner là où ils sont et restent listés.

Copier les fichiers locaux ignorés dans les nouveaux worktrees

Un nouveau worktree part d'un checkout Git, les fichiers suivis sont donc déjà là. Les fichiers ignorés par Git ne le sont pas, et un worktree en a souvent besoin de quelques-uns pour tourner : .env, .env.local, un fichier de secrets local.

Ajoutez un fichier .worktreeinclude à la racine du dépôt et listez les chemins ignorés à copier, un par ligne, relatifs à la racine. Les dossiers fonctionnent aussi, avec ou sans / final, et # commence un commentaire.

# .worktreeinclude
.env
.env.local
config/secrets.json

Sans ce fichier, Paneflow copie les .env* de premier niveau et AGENTS.override.md s'ils existent. Un fichier déjà présent dans le worktree n'est jamais écrasé. Ne listez pas de fichiers suivis ; Git les apporte déjà.

Nettoyage

Les worktrees prennent de la place : chacun porte ses propres fichiers, dépendances et caches de build. Paneflow garde leur nombre raisonnable de lui-même.

Par défaut, Paneflow conserve vos 15 worktrees gérés les plus récents. Changez la limite ou désactivez la suppression automatique dans Settings > Worktrees, ou avec worktrees.keep_limit et worktrees.auto_remove dans paneflow.json.

Un worktree géré est supprimé automatiquement quand :

• vous fermez l'espace de travail auquel il appartient ;
• Paneflow doit rogner les plus anciens pour rester sous la limite de conservation.

Un worktree géré n'est jamais supprimé automatiquement tant qu'un onglet d'un espace de travail ouvert l'utilise. La branche n'est jamais supprimée non plus : supprimer un worktree ne supprime que le checkout, vos commits restent sur la branche.

Vous pouvez aussi supprimer un worktree à la main depuis Settings > Worktrees, ou depuis le menu contextuel de l'onglet. Paneflow ne supprime que les worktrees qu'il a créés ; ceux que vous avez faits vous-même avec git worktree add sont laissés tranquilles.

Snapshots

Avant de supprimer un worktree géré, automatiquement ou à la main, Paneflow sauvegarde son travail non commité dans un snapshot : éditions de fichiers suivis, nouveaux fichiers et la branche sur laquelle était le worktree. Un worktree propre ne laisse aucun snapshot.

Les snapshots sont des commits Git ordinaires rangés sous refs/paneflow/snapshots/ dans votre dépôt. Ils ne touchent pas vos branches, ne sont jamais poussés, et vous pouvez les inspecter avec git log refs/paneflow/snapshots/<nom> si vous le souhaitez.

Settings > Worktrees les liste sous « Snapshots » :

• Restore recrée le worktree à son chemin d'origine, sur la même branche, avec les modifications sauvegardées de retour en non commité, et recopie vos fichiers .worktreeinclude.
• Delete supprime le snapshot pour de bon.

Supprimer un worktree dont vous ne voulez plus des modifications est une opération en deux temps, volontairement : supprimer, puis effacer le snapshot.

Questions fréquentes

Puis-je choisir où les worktrees sont créés ?

Oui. Définissez la racine dans Settings > Worktrees ou avec worktrees.dir. ~ se développe en votre dossier personnel, et PANEFLOW_HOME déplace tout le dossier ~/.paneflow, worktrees compris.

Qu'advient-il de mon travail quand un worktree est supprimé ?

Vos commits restent sur la branche. Les modifications non commitées vont dans un snapshot que vous pouvez restaurer depuis Settings > Worktrees. Choisissez à nouveau la branche dans la palette « New pane » pour obtenir un worktree neuf depuis son état commité.

Puis-je déplacer du travail entre un worktree et le checkout du projet ?

Commitez ou stashez sur le worktree, puis basculez le checkout du projet sur la branche, soit depuis le formulaire « New branch… » avec le toggle Worktree désactivé, soit avec git switch. Git refusera tant que la branche est encore checkoutée dans le worktree, supprimez donc d'abord ce worktree depuis Settings > Worktrees.

Paneflow touche-t-il aux worktrees que j'ai créés moi-même ?

Non. Paneflow les liste dans la ligne de branche et y ouvre des panes, mais ne supprime jamais un worktree qu'il n'a pas créé.

Deux tâches, puis une intégration

Pour Paneflow 0.17.4, partez d'une base commitée dans un projet Git jetable. Suivez la procédure New branch... ci-dessus avec Worktree activé :

1. Créez feat/api-validation pour une tâche et test/api-validation pour ses tests, depuis la même base. Vérifiez le chemin et la branche de chaque onglet avant de lancer un agent.
2. Attribuez explicitement les fichiers à chaque tâche et utilisez des ports différents pour les serveurs. Installez les dépendances dans le bon checkout. Les changements non commités du checkout principal ne deviennent pas des fichiers suivis du nouveau worktree ; commitez la base voulue si les deux tâches en ont besoin.
3. Sauvegardez, lisez Changes par rapport au HEAD de chaque checkout, puis commitez et relisez le diff complet de branche avec Git. Changes n'est pas une revue depuis le merge-base.
4. Intégrez les commits relus dans le checkout d'intégration choisi, résolvez les conflits et lancez les tests pertinents ensemble. Gardez les deux checkouts tant que leur travail utile n'est pas préservé.

Historique, remotes et références de branches sont partagés. Ports, bases de données, accès réseau et permissions utilisateur ne sont pas isolés. .worktreeinclude peut copier des secrets locaux ; choisissez les fichiers nécessaires à chaque tâche. Un worktree n'est pas une sandbox de sécurité.

Branche ouverte, projet non Git ou édition non sauvegardée

Une branche déjà extraite réutilise son checkout existant, sans créer une seconde copie indépendante. Vérifiez le chemin avant de supposer une isolation. Un projet non Git n'a pas de gestion de worktrees Git ; utilisez son répertoire courant ou initialisez Git délibérément.

Sauvegardez ou abandonnez explicitement les buffers avant de changer ou supprimer un checkout. Les snapshots lisent les fichiers du disque, pas le texte non enregistré. Le changement du checkout principal est aussi refusé si un agent y travaille. Si Git refuse parce que des fichiers seraient écrasés, préservez-les et résolvez la cause sans nettoyage forcé.

Consultez Changes pour la portée de la revue et Files pour les conflits de sauvegarde.

Voir aussi

• Référence de configuration : chaque clé worktrees.*.
• Scripting : worktree et from dans paneflow up.
• Paramètres : la page Worktrees.