Worktrees

Les worktrees vous permettent de faire tourner plusieurs agents sur le même projet sans qu'ils se marchent dessus. Chacun reçoit son propre checkout du dépôt, sur sa propre branche, avec ses propres panes et sessions d'agent, tandis que le dépôt, les worktrees et les commandes restent sur votre machine.

Paneflow crée et supprime ces worktrees pour vous. Avant d'en supprimer un, il sauvegarde le travail non commité dans un snapshot que vous pourrez restaurer plus tard.

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 modifications non commitées d'un worktree juste avant de le supprimer, pour que rien ne soit perdu.

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.
• Relire le résultat plus tard dans Revue, côte à côte avec d'autres worktrees, sans rien checkouter.

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 à trois autres endroits :

• Le Launch Pad a un champ « New branch » et le même sélecteur « From ».
• 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.

Worktrees et Revue

Revue lit les worktrees sans rien checkouter. Glissez une branche ou un worktree sur le bord d'un pane pour lire son diff par rapport à la base choisie, jusqu'à six côte à côte. Supprimer un worktree le retire aussi de Revue.

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éé.

Voir aussi

• Référence de configuration : chaque clé worktrees.*.
• Revue : lire les diffs des worktrees côte à côte.
• Scripting : worktree et from dans paneflow up.
• Paramètres : la page Worktrees.