Worktrees

Les worktrees permettent à Codex d’exécuter plusieurs conversations indépendantes dans un même projet sans qu’elles interfèrent entre elles. Le dépôt, le worktree et les commandes restent sur l’ordinateur ou dans l’environnement de développement distant qui contient le projet. Vous pouvez travailler directement dans l’application de bureau ChatGPT ou utiliser Remote dans l’application mobile ChatGPT pour démarrer, guider, approuver et examiner des conversations de worktree sur un ordinateur connecté.

Pour les dépôts Git, les tâches planifiées peuvent s’exécuter dans des worktrees d’arrière-plan dédiés afin de ne pas entrer en conflit avec votre travail en cours. Dans les projets sans gestion de versions, les tâches planifiées s’exécutent directement dans le répertoire du projet. Vous pouvez également démarrer manuellement des conversations dans un worktree et utiliser Handoff pour déplacer une conversation entre Local et Worktree.

Qu’est-ce qu’un worktree ?

Les worktrees fonctionnent uniquement dans les projets qui font partie d’un dépôt Git, car ils reposent sur les worktrees Git. Un worktree vous permet de créer une deuxième copie (« checkout ») de votre dépôt. Chaque worktree possède sa propre copie de chaque fichier du dépôt, mais tous partagent les mêmes métadonnées (dossier .git) concernant les commits, les branches, etc. Vous pouvez ainsi extraire plusieurs branches et travailler dessus en parallèle.

Terminologie

• Checkout local : dépôt que vous avez créé. Parfois simplement appelé Local dans l’app de bureau ChatGPT.
• Worktree : worktree Git créé à partir de votre checkout local dans l’app de bureau ChatGPT.
• Handoff : processus qui déplace un chat entre Local et Worktree. Codex gère les opérations Git nécessaires pour déplacer votre travail de l’un à l’autre en toute sécurité.

Pourquoi utiliser un worktree ?

1. Travaillez en parallèle avec Codex sans perturber votre configuration Local actuelle.
2. Mettez du travail en file d’attente en arrière-plan tout en restant concentré sur ce qui se passe au premier plan.
3. Déplacez ultérieurement un chat vers Local lorsque vous êtes prêt à inspecter, tester ou collaborer plus directement.

Prise en main

Les worktrees nécessitent un dépôt Git. Assurez-vous que le projet sélectionné se trouve dans un tel dépôt.

1. Sélectionnez « Worktree »

   Dans la vue d’un nouveau chat, sélectionnez Worktree sous la zone de rédaction. Vous pouvez également choisir un environnement local pour exécuter des scripts de configuration destinés au worktree.

2. Sélectionnez la branche de départ

   Sous la zone de rédaction, choisissez la branche Git sur laquelle baser le worktree. Il peut s’agir de votre branche main / master, d’une branche de fonctionnalité ou de votre branche actuelle avec des modifications locales non indexées.

3. Envoyez votre prompt

   Envoyez votre prompt : Codex crée alors un worktree Git basé sur la branche sélectionnée. Par défaut, Codex travaille avec un « HEAD détaché ».

4. Choisissez où poursuivre le travail

   Lorsque vous êtes prêt, vous pouvez soit continuer à travailler directement dans le worktree, soit transférer le chat vers votre checkout local. Un transfert vers ou depuis Local déplace à la fois votre chat et votre code afin que vous puissiez poursuivre dans l’autre checkout.

Travailler entre Local et Worktree

L’apparence et le fonctionnement des worktrees sont très proches de ceux de votre checkout local. La différence tient à leur place dans votre workflow. Vous pouvez considérer Local comme le premier plan et Worktree comme l’arrière-plan. Handoff vous permet de déplacer un chat de l’un à l’autre.

En coulisses, Handoff gère les opérations Git nécessaires pour déplacer le travail en toute sécurité entre deux checkouts. C’est important, car Git permet uniquement d’extraire une branche à un seul endroit à la fois. Si vous extrayez une branche dans un worktree, vous ne pouvez pas l’extraire simultanément dans votre checkout local, et inversement.

En pratique, deux parcours sont courants :

1. Travailler exclusivement dans le worktree. Ce parcours est particulièrement adapté lorsque vous pouvez vérifier les modifications directement dans le worktree, par exemple parce que vous avez installé les dépendances et les outils à l’aide d’un script de configuration de l’environnement local.
2. Transférer le chat vers Local. Utilisez ce parcours lorsque vous souhaitez ramener le chat au premier plan, par exemple pour inspecter les modifications dans votre IDE habituel ou parce que vous ne pouvez exécuter qu’une seule instance de votre app.

Option 1 : travailler dans le worktree

Si vous souhaitez conserver exclusivement vos modifications dans le worktree, transformez celui-ci en branche à l’aide du bouton Créer une branche ici dans l’en-tête du chat.

Vous pouvez ensuite effectuer un commit de vos modifications, pousser votre branche vers votre dépôt distant et ouvrir une pull request sur GitHub.

Vous pouvez ouvrir votre IDE dans le worktree à l’aide du bouton Ouvrir de l’en-tête, utiliser le terminal intégré ou tout autre outil dont vous avez besoin depuis le répertoire du worktree.

Option 2 : transférer un chat vers Local

Si vous souhaitez ramener un chat au premier plan, sélectionnez Transférer dans l’en-tête du chat, puis déplacez-le vers Local.

Ce parcours convient bien lorsque vous souhaitez lire les modifications dans la fenêtre habituelle de votre IDE, exécuter votre serveur de développement existant ou valider le travail dans l’environnement que vous utilisez déjà au quotidien.

Codex gère les étapes Git nécessaires pour déplacer le chat en toute sécurité entre le worktree et votre checkout local.

Chaque conversation reste associée au même worktree au fil du temps. Si vous retransférez ultérieurement la conversation vers un worktree, Codex la renvoie dans ce même environnement d’arrière-plan afin que vous puissiez reprendre là où vous vous étiez arrêté.

Comme Handoff utilise des opérations Git, les fichiers faisant partie de votre fichier .gitignore ne sont pas déplacés avec le chat, sauf si Codex les copie dans un worktree local géré à l’aide de .worktreeinclude.

Détails avancés

Worktrees gérés par Codex et worktrees permanents

Par défaut, les chats utilisent un worktree géré par Codex. Ces worktrees sont conçus pour être légers et jetables. Un worktree géré par Codex est généralement consacré à un seul chat, et Codex renvoie ce chat dans le même worktree si vous le retransférez ultérieurement.

Si vous souhaitez disposer d’un environnement durable, créez un worktree permanent depuis le menu à trois points d’un projet dans la barre latérale. Cette opération crée un nouveau worktree permanent sous forme de projet distinct. Les worktrees permanents ne sont pas supprimés automatiquement et vous pouvez démarrer plusieurs chats depuis le même worktree.

Comment Codex gère les worktrees pour vous

Codex crée les worktrees dans $CODEX_HOME/worktrees. Le commit de départ est le commit HEAD de la branche sélectionnée au démarrage de votre conversation. Si vous avez choisi une branche comportant des modifications locales, Codex applique également les modifications non validées au worktree. Le worktree n’est pas extrait en tant que branche. Il se trouve dans un état detached HEAD. Cela permet à Codex de créer plusieurs worktrees sans encombrer vos branches.

Copier des fichiers locaux ignorés dans les worktrees gérés

Les worktrees locaux gérés par Codex sont créés à partir d’un checkout Git, de sorte que les fichiers suivis sont déjà présents. Si votre dépôt ignore des fichiers de configuration locaux nécessaires à un nouveau worktree, ajoutez un fichier .worktreeinclude à la racine du dépôt et répertoriez les chemins ignorés ou les motifs de type .gitignore à copier lorsque Codex crée un worktree géré.

Utilisez cette fonctionnalité pour les fichiers intentionnellement ignorés par Git, tels que .env, .env.local ou config/secrets.json. Codex copie uniquement les fichiers ignorés correspondant à .worktreeinclude ; il ne copie pas les autres fichiers locaux non suivis par Git. Ne répertoriez pas les fichiers suivis.

Codex copie automatiquement un fichier AGENTS.override.md ignoré dans les worktrees locaux gérés. Il n’est donc pas nécessaire de le répertorier dans .worktreeinclude.

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

Codex ignore les liens symboliques sources et ne remplace pas les fichiers qui existent déjà dans le nouveau checkout. Ce comportement s’applique aux worktrees locaux gérés par l’app de bureau ChatGPT, et non aux worktrees distants ni aux worktrees Git que vous créez vous-même depuis la ligne de commande.

Limitations liées aux branches

Supposons que Codex termine un travail dans un worktree et que vous choisissiez d’y créer une branche feature/a à l’aide de Créer une branche ici. Vous souhaitez maintenant l’essayer dans votre checkout local. Si vous tentiez d’extraire la branche, vous obtiendriez l’erreur suivante :

fatal: 'feature/a' is already used by worktree at '<WORKTREE_PATH>'

Pour résoudre ce problème, vous devez extraire une autre branche que feature/a dans le worktree.

Si vous prévoyez d’extraire la branche localement, utilisez Handoff pour déplacer le chat vers Local au lieu d’essayer de conserver la même branche extraite simultanément aux deux endroits.

Nettoyage des worktrees

Les worktrees peuvent occuper beaucoup d’espace disque. Chacun possède son propre ensemble de fichiers du dépôt, de dépendances, de caches de compilation, etc. Par conséquent, l’app de bureau ChatGPT s’efforce de maintenir le nombre de worktrees à une limite raisonnable.

Par défaut, Codex conserve vos 15 worktrees gérés par Codex les plus récents. Vous pouvez modifier cette limite ou désactiver la suppression automatique dans les paramètres si vous préférez gérer vous-même l’utilisation du disque.

Codex s’efforce d’éviter de supprimer les worktrees qui restent importants. Les worktrees gérés par Codex ne sont pas supprimés automatiquement dans les cas suivants :

• Un chat épinglé leur est associé
• Le chat est toujours en cours
• Le worktree est permanent

Les worktrees gérés par Codex sont supprimés automatiquement dans les cas suivants :

• Vous archivez le chat associé
• Codex doit supprimer d’anciens worktrees pour respecter la limite configurée

Avant de supprimer un worktree géré par Codex, Codex enregistre un instantané du travail qu’il contient. Si vous ouvrez un chat après la suppression de son worktree, une option vous permet de le restaurer.

Questions fréquentes