Arborescences de travail Git isolées (Worktrees) : paralléliser le travail
📚 Navigation dans la série : Le chapitre précédent [24 · Règles et points de contrôle d'exécution (Hooks)] a montré comment mettre en place des règles et des hooks pour automatiser la validation de code. Ce chapitre aborde la parallélisation des tâches au sein de votre dépôt : l'arborescence de travail (Worktree) de Git est la méthode clé utilisée par Codex pour faire coexister plusieurs fils de tâches indépendants sans interférences de fichiers. Nous verrons comment initialiser ces environnements, comment contourner la contrainte de verrouillage de branche unique de Git, et comment la fonctionnalité de transfert Handoff permet de basculer une tâche entre le premier et l'arrière-plan. Le chapitre suivant [26 · Intégration Git et GitHub] détaillera la soumission de commits et la création de Pull Requests.
Permettez-moi de vous raconter une erreur commise en mars dernier.
Voulant gagner du temps, j'ai ouvert deux sessions locales distinctes au sein de l'application de bureau Codex pour travailler sur le même dépôt de code : la première devait restructurer la couche d'accès aux données, la seconde modifier le système de routage. Je pensais ainsi doubler ma vitesse de traitement. Les deux instances ont modifié simultanément le fichier config.ts, et la validation de la seconde session a écrasé la moitié des modifications de la première. Face aux conflits de commits de mon git diff, j'ai dû me rendre à l'évidence : le problème ne venait pas de Codex, mais de ma méthode. Je faisais travailler deux instances sur le même fichier physique.
Depuis, j'utilise la solution appropriée : le système d'arborescences de travail (Worktree). Pour mener des tâches en parallèle sur le même projet, j'initialise des répertoires de travail isolés. Les instances ne risquent plus d'écraser le travail en cours.
Comme vu au chapitre 7 présentant l'application de bureau, l'arborescence de travail (Worktree) constitue l'un des trois modes d'exécution d'une session (avec Local et Cloud, le mode Cloud étant détaillé au chapitre 10). Ce chapitre détaille le fonctionnement de l'isolation, la contrainte de verrouillage de branche unique de Git, le fonctionnement des transferts Handoff et la gestion de l'espace disque.
À la fin de ce chapitre, vous aurez en main :
- Le rôle d'un worktree Git et sa différence fondamentale avec l'ouverture de multiples sessions locales sur le même répertoire.
- Les étapes pour initialiser une session Worktree dans l'application de bureau, et le fonctionnement de l'état initial en tête détachée (detached HEAD).
- La règle de verrouillage de Git — l'impossibilité de charger une même branche dans deux répertoires de travail distincts —, ses messages d'erreur et ses contournements.
- Les deux scénarios d'utilisation de la fonction de transfert Handoff pour basculer une tâche de Local à Worktree (et inversement).
- L'usage des scripts d'initialisation des environnements locaux (Local environments) pour automatiser l'installation des dépendances dans vos nouveaux worktrees.
- La politique de nettoyage automatique des dossiers de worktrees pour limiter l'impact sur l'espace disque de votre machine.
⚠️ Note de plateforme : Les fonctionnalités de Worktree, Handoff et d'environnements locaux (Local environments) sont propres à l'application de bureau Codex. Le CLI ne dispose pas de commandes équivalentes pour ces opérations. Fiez-vous aux interfaces de votre application.
01 Le rôle des worktrees Git : Paralléliser sans interférences
En résumé : le système de worktrees permet de traiter simultanément plusieurs tâches indépendantes sur le même dépôt Git, en affectant à chaque fil de tâche un répertoire physique isolé. Cela évite que les instances ne modifient les mêmes fichiers en même temps.
Jusqu'ici, nous avons étudié des traitements exécutés au sein d'une session de travail unique : une consigne est fournie, et Codex modifie le code de votre répertoire de travail. Cette approche suffit pour la majorité des modifications. Elle présente toutefois des limites dans deux situations :
1. Le besoin de mener des analyses indépendantes en parallèle : si vous devez corriger un bug d'API, modifier le style d'un bouton et enrichir les tests unitaires du projet, mener ces tâches l'une après l'autre de manière séquentielle rallonge le temps de livraison alors qu'elles n'ont pas de dépendances techniques entre elles. 2. L'expérimentation d'une idée sans polluer vos modifications courantes : vous travaillez sur une évolution complexe non validée. Une idée d'optimisation survient ; modifier le code sur votre répertoire courant risque de corrompre vos modifications en cours si l'expérimentation échoue.
L'ouverture de plusieurs sessions d'IA locales sur le même dossier provoque des conflits de modifications, car les instances réécrivent les mêmes fichiers.
Analogie : Les copies de travail d'un dossier médical. Si trois médecins spécialistes doivent formuler des prescriptions en parallèle sur le même dossier physique papier, et que chacun tente d'écrire en même temps sur l'unique feuille de soins, les écritures vont se chevaucher ou s'écraser. La procédure consiste à remettre à chaque spécialiste une copie autonome du dossier de soins pour qu'il rédige ses conclusions de son côté. Ces conclusions sont ensuite reportées sur le dossier principal. Le système de worktrees applique cette méthode : il crée des répertoires de travail physiques distincts, tout en conservant une base de données Git unique (le dossier .git regroupant l'historique et les index). Les modifications appliquées par une instance sur sa copie n'impactent pas le code des autres copies.
La documentation officielle le résume ainsi :
Chaque worktree possède sa propre copie physique de tous les fichiers de votre dépôt, mais partage la même base de données de métadonnées Git (le dossier
.git). Cela vous permet de charger et de traiter plusieurs branches en parallèle.
Cas d'usages types :
- Traiter en parallèle la correction d'un bug d'API et l'ajout d'une page dans deux sessions isolées.
- Tester une architecture expérimentale dans une session Worktree temporaire sans toucher à votre répertoire principal, avec la liberté de détruire le dossier si le test est rejeté.
- Déporter une tâche de refactorisation lourde en arrière-plan dans une session Worktree, tout en conservant votre répertoire principal disponible pour vos modifications courantes.
💡 En résumé : Le worktree Git isole les fichiers de chaque session de travail pour vous permettre de mener des tâches en parallèle. Les instances travaillent sur des copies distinctes partageant la même base de données de commits.
02 Initialiser une session Worktree dans l'application de bureau
L'initialisation d'un worktree s'effectue graphiquement dans l'application de bureau Codex, sans saisie de commande Git.
Le dépôt de code ciblé doit être un dépôt Git valide pour que l'application de bureau puisse utiliser les commandes Git sous-jacentes.
Étapes de création
Étape 1 : Sélectionner le mode Worktree : Lors de la création d'une nouvelle session, sous la zone de saisie du message, modifiez le mode d'exécution (par défaut réglé sur Local) pour sélectionner Worktree. Étape 2 : Définir la branche d'origine : Indiquez à partir de quel état Git le worktree doit être créé. Vous pouvez cibler le commit principal (main ou master), une branche d'évolution existante, ou votre état local courant incluant les modifications non validées (unstaged changes). Cette option permet d'exporter vos modifications courantes dans un dossier isolé pour poursuivre le travail. Étape 3 : Soumettre les consignes : Saisissez vos instructions dans le chat. Codex initialise le répertoire Git worktree et lance le traitement. Étape 4 : Valider le dossier d'arrivée : Une fois les modifications appliquées, vous pouvez poursuivre le travail sur ce répertoire ou rapatrier les modifications vers votre dossier principal (fonction Handoff, détaillée à la section 04).
Comprendre le fonctionnement de la tête détachée (detached HEAD)
Par défaut, les sessions Worktree de Codex s'initialisent sous un état Git particulier : la tête détachée (detached HEAD). Cela signifie que le pointeur de travail cible un commit de référence spécifique plutôt qu'un nom de branche Git.
La documentation officielle le précise :
Par défaut, Codex travaille au sein des worktrees en état de « tête détachée » (detached HEAD).
Cette méthode permet à Codex d'initialiser de multiples sessions Worktree en parallèle sans encombrer votre dépôt Git de dizaines de noms de branches temporaires.
Si vous souhaitez valider les modifications et les intégrer à votre historique, vous devez créer une branche Git sur cet état. Cliquez sur le bouton Create branch here (Créer une branche ici) situé dans l'en-tête de la session pour affecter un nom de branche au worktree courant, ce qui vous permettra de soumettre vos commits ou de créer une Pull Request.
💡 En résumé : Le mode Worktree s'active graphiquement en choisissant la branche de départ. Le répertoire est créé sous l'état détaché (detached HEAD) par sécurité ; utilisez le bouton Create branch here pour lui associer une branche Git nominative.
03 La règle de verrouillage de branche unique de Git
Cette section aborde une contrainte de fonctionnement inhérente à Git.
Règle de sécurité de Git : une même branche Git ne peut pas être chargée simultanément dans deux répertoires de travail distincts. Si une branche est active dans votre répertoire local principal (Local), elle ne peut pas être chargée dans un répertoire isolé (Worktree) en parallèle.
Analogie : L'emprunt d'un document physique original. Si un document original est en cours d'utilisation par un collaborateur dans un bureau, un autre collaborateur ne peut pas l'utiliser dans son bureau. L'état d'avancement du document devant rester unique, le système interdit son double usage. Pour travailler sur le sujet, le second collaborateur doit travailler sur une copie ou sur une autre version. Git applique ce principe de verrouillage sur ses branches.
Si vous tentez d'initialiser un worktree sur une branche déjà chargée dans un autre répertoire de votre machine, Git rejettera l'opération avec le message d'erreur suivant :
fatal: 'ma-branche' is already used by worktree at '/chemin/vers/autre-repertoire'Pour contourner ce verrouillage :
- Modifiez la branche active de l'autre répertoire pour libérer celle que vous ciblez.
- Ou utilisez la fonction de transfert Handoff de Codex (présentée à la section 04) pour basculer proprement le fil de tâche vers votre dossier de travail principal.
💡 En résumé : Git interdit le chargement d'une même branche dans deux dossiers en même temps. En cas d'erreur de verrouillage, modifiez la branche de l'autre répertoire ou utilisez la fonction Handoff.
04 La fonction Handoff : Basculer les tâches entre premier et arrière-plan
La fonction de transfert Handoff gère les bascules de répertoires de travail de Codex.
Dans l'application de bureau, le répertoire Local représente votre premier plan (votre espace d'édition usuel), et le répertoire Worktree représente l'arrière-plan (l'espace d'exécution isolé). La fonction Handoff permet de transférer un fil de discussion et ses modifications de l'un à l'autre.
Analogie : Les cuisines d'un restaurant. Le comptoir principal (Local) est l'espace où le chef finalise le dressage et présente les plats. La cuisine de préparation (Worktree) est le laboratoire où s'effectuent les cuissons longues en arrière-plan. Si un plat demande une longue préparation, il est déporté en cuisine de préparation. Une fois prêt pour le dressage final, il est ramené sur le comptoir principal. La fonction Handoff effectue ces transferts de plats.
La documentation officielle indique que Handoff permet de résoudre la contrainte de verrouillage de branche unique de Git en déplaçant proprement les index de travail :
La fonction Handoff permet de basculer la branche active vers votre espace de travail principal.
Les transferts s'effectuent selon deux directions :
Direction 1 : De Worktree (arrière-plan) vers Local (premier plan) : Cliquez sur le bouton Hand off et sélectionnez Local. Ce mode est recommandé lorsque vous souhaitez vérifier les modifications appliquées par Codex au sein de votre éditeur de code usuel, ou si le lancement du serveur de développement local n'autorise qu'une seule instance active sur la machine. Direction 2 : De Local (premier plan) vers Worktree (arrière-plan) : Transférez le fil vers un répertoire isolé pour libérer votre espace de travail principal et confier à Codex une refactorisation en arrière-plan, tout en poursuivant vos modifications courantes en local.
Règle de persistance : chaque fil de discussion reste associé à son répertoire de worktree d'origine. Si vous basculez un fil en Local puis le renvoyez en Worktree, Codex le rapatrie dans le dossier d'origine pour conserver votre historique de travail.
Attention toutefois aux fichiers exclus :
Les transferts Handoff s'appuyant sur des commandes Git, tous les fichiers listés dans votre fichier
.gitignorene seront pas transférés vers le répertoire de destination.
Les fichiers de configuration de clés (comme .env) ou les dossiers de dépendances installés en local (comme node_modules) ne sont pas suivis par Git et restent dans leur répertoire d'origine. La section suivante présente la solution pour initialiser ces fichiers dans les nouveaux répertoires.
| Direction de transfert | Usage principal | Fichiers exclus (.gitignore) |
|---|---|---|
| Worktree → Local | Revue de code dans votre IDE, validation de rendu local | Restent dans le répertoire d'origine |
| Local → Worktree | Libération de l'espace principal pour des tâches de fond | Restent dans le répertoire d'origine |
💡 En résumé : La fonction Handoff bascule une tâche entre votre espace principal (Local) et l'espace isolé (Worktree) sans manipulation de console. Les fichiers non suivis par Git (déclarés dans
.gitignore) ne sont pas transférés.
05 Automatiser l'installation des dépendances (Local environments)
Puisqu'un worktree est une copie de fichiers neuve issue de Git, les éléments exclus de l'indexation (dépendances du dossier node_modules ou clés du fichier .env) sont absents lors de sa création. Lancer un outil ou des tests dans ce dossier provoquera des erreurs de modules manquants.
Pour y remédier, configurez un script d'initialisation au sein des environnements locaux (Local environments). Lors de la création d'un worktree, Codex exécute automatiquement ce script d'initialisation pour installer les dépendances et générer les fichiers locaux.
Analogie : La check-list d'ouverture d'une succursale. Le bâtiment de la succursale (le répertoire du worktree) est livré vide. L'entreprise utilise une check-list d'installation (« brancher l'électricité, installer le réseau, livrer les ordinateurs ») pour rendre le bureau opérationnel. Le script d'initialisation est cette check-list pour votre répertoire de code.
La configuration s'effectue ainsi :
- Déclarez l'environnement local dans le panneau Settings de l'application de bureau. Codex enregistre les paramètres dans le dossier de configuration
.codexà la racine de votre projet. - Intégrez ce dossier
.codexau dépôt Git pour partager ces scripts d'initialisation avec les membres de votre équipe.
Exemple de script d'initialisation pour un projet TypeScript :
npm install
npm run buildDès la création du répertoire, Codex exécute ces commandes pour installer les packages et compiler les sources, mettant à disposition un environnement prêt pour les modifications.
Vous pouvez déclarer des scripts d'initialisation spécifiques par système d'exploitation (macOS, Windows, Linux) pour gérer les particularités de commande de chaque plateforme.
💡 En résumé : Utilisez les scripts d'initialisation des environnements locaux (enregistrés sous
.codex/) pour installer automatiquement les dépendances non indexées (comme les packages npm) dans vos nouveaux dossiers de worktrees.
06 Gestion de l'espace disque et nettoyage automatique
La création de répertoires de travail en parallèle consomme de l'espace sur votre disque dur, chaque dossier intégrant les fichiers du projet et ses dépendances de compilation.
Pour limiter cet impact, Codex intègre une politique de nettoyage automatique des dossiers de worktrees obsolètes :
- Les répertoires de worktrees sont centralisés sous le répertoire de données de l'application :
$CODEX_HOME/worktrees(par défaut~/.codex/worktrees/). - Par défaut, Codex conserve un maximum de 15 répertoires de worktrees actifs sur la machine. Vous pouvez modifier cette limite ou désactiver le nettoyage automatique dans les paramètres de l'application.
La suppression automatique des dossiers respecte des règles de sécurité pour préserver votre travail :
Les dossiers de worktrees exclus de la suppression automatique :
- Le fil de discussion associé au worktree est épinglé (pinned) dans l'historique.
- La tâche associée au worktree est en cours d'exécution.
- Le répertoire a été marqué comme permanent (Permanent Worktree, voir ci-dessous).
Les dossiers de worktrees éligibles à la suppression automatique :
- Le fil de discussion associé a été archivé (archived).
- Codex doit libérer de l'espace pour respecter la limite maximale de dossiers configurée.
Une sécurité importante protège vos modifications en cas de suppression :
Avant de supprimer un dossier de worktree géré, Codex enregistre une copie de sauvegarde (un instantané) de l'état des fichiers. Si vous réouvrez le fil de discussion correspondant ultérieurement, l'application vous propose de restaurer l'intégralité du répertoire.
Comparatif des types de worktrees :
| Caractéristique | Worktree géré par Codex (par défaut) | Worktree permanent (Permanent Worktree) |
|---|---|---|
| Mode de création | Automatique lors du choix du mode Worktree en session | Manuelle via le menu d'options de l'onglet du projet |
| Liaison | Associé au fil de discussion d'une tâche unique | Peut être réutilisé pour initialiser plusieurs sessions |
| Suppression | Supprimé automatiquement en cas d'archivage ou de dépassement de limite | Exclu du nettoyage automatique |
| Usage recommandé | Tâches de développement courtes d'une session | Environnement d'expérimentation à long terme |
💡 En résumé : Les dossiers de worktrees sont stockés sous
~/.codex/worktrees/. L'application de bureau conserve au maximum 15 dossiers actifs et gère un nettoyage automatique, tout en conservant une copie de sauvegarde des modifications supprimées pour permettre leur restauration.
07 En pratique : Initialiser et tester un worktree isolé
Voici un exercice pratique pour initialiser un worktree, vérifier son isolation en console et valider son transfert via la fonction Handoff.
Note technique : Cet exercice s'effectue au sein de l'application de bureau Codex sur un projet configuré sous Git.
Étape 1 : Créer une session Worktree
Ouvrez votre projet sous l'application de bureau Codex. Créez un nouveau fil de discussion, sélectionnez le mode Worktree sous la zone de saisie du message, puis sélectionnez la branche main (ou master) comme origine.
Étape 2 : Lancer une consigne d'analyse
Saisissez une consigne d'analyse simple dans le chat :
Recherche et liste les fichiers markdown (.md) présents dans ce projet.Comportement attendu : Codex crée le répertoire de worktree dans son dossier de données, et l'assistant s'exécute au sein de cette copie de fichiers pour lister les chemins.
Étape 3 : Vérifier l'isolation en console
Ouvrez la console intégrée de la session de discussion (raccourci Cmd + J sur macOS ou la touche d'affichage associée) et interrogez la liste des répertoires de travail de Git :
git worktree listComportement attendu : La console liste deux chemins d'accès actifs : votre répertoire principal (Local) et le répertoire d'arrière-plan de Codex (situé sous ~/.codex/worktrees/), confirmant l'isolation physique du dossier d'exécution.
Étape 4 : Tester la fonction de transfert Handoff
Cliquez sur le bouton Hand off situé dans l'en-tête de la session de discussion, puis sélectionnez Local.
Comportement attendu : Codex transfère la branche active et l'historique du fil vers votre espace de travail principal. Vous pouvez inspecter les modifications au sein de votre éditeur de code usuel.
Étape 5 : Nettoyer l'environnement
Pour libérer l'espace disque du répertoire créé, archivez le fil de discussion associé au sein de votre liste d'historique. Le dossier temporaire sous ~/.codex/worktrees/ est alors éligible au nettoyage automatique.
💡 En résumé : L'exercice montre la création d'un worktree, la validation de son isolation physique via
git worktree list, son transfert dans votre espace principal avec Handoff, et sa mise au rebut par l'archivage du fil.
08 Résumé
Ce chapitre a présenté l'usage des arborescences de travail (Worktrees) pour paralléliser vos tâches de développement sans conflit de fichiers.
Voici les points clés à retenir :
| Aspect | Règle de fonctionnement |
|---|---|
| Utilité | Permet de mener plusieurs tâches en parallèle sur le même dépôt en isolant les répertoires physiques. |
| Tête détachée | Les worktrees s'initialisent par défaut en état détaché (detached HEAD) pour ne pas polluer l'historique. |
| Verrouillage | Git interdit le chargement d'une même branche dans deux répertoires de travail distincts. |
| Handoff | Transfert le fil et ses index entre l'espace principal (Local) et l'espace isolé (Worktree). |
| Initialisation | Utilise les scripts de configuration d'environnements locaux (.codex/) pour installer les dépendances. |
| Espace disque | Stocké sous ~/.codex/worktrees/ ; Codex limite à 15 dossiers actifs avec sauvegarde de restauration. |
Vous êtes désormais en mesure de comprendre l'intérêt d'utiliser des répertoires isolés, d'initialiser une session Worktree dans l'application de bureau, de gérer les contraintes de verrouillage de branches de Git, d'utiliser la fonction Handoff pour transférer vos tâches, d'automatiser la configuration d'un nouveau répertoire via les scripts d'initialisation, et de contrôler l'occupation d'espace disque des copies temporaires.
Le chapitre suivant 26 · Intégration Git et GitHub présente la soumission de votre code : comment Codex gère-t-il la création de commits, la rédaction de messages descriptifs, la gestion des Pull Requests et l'interaction avec GitHub ? Nous verrons comment valider et publier nos travaux.