Documentation ChatGPT
Français
Contact goolvyouyou@gmail.com

Worktrees

Utilisez les worktrees Git dans Codex au sein de l’application de bureau ChatGPT pour exécuter des chats en parallèle

Dans l’application de bureau ChatGPT, les worktrees permettent à Codex d’exécuter plusieurs chats indépendants au sein d’un même projet sans qu’ils interfèrent les uns avec les autres. Pour les dépôts Git, les tâches planifiées peuvent s’exécuter dans des worktrees dédiés en arrière-plan 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 chats dans un worktree et utiliser Handoff pour déplacer un chat entre Local et Worktree.

Qu’est-ce qu’un worktree ?

Les worktrees fonctionnent uniquement dans les projets appartenant à un dépôt Git, car ils reposent sur les worktrees Git. Un worktree vous permet de créer une seconde copie (« checkout ») de votre dépôt. Chaque worktree possède sa propre copie de chaque fichier de votre 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 : le dépôt que vous avez créé. Il est parfois simplement appelé Local dans l’application de bureau ChatGPT.
  • Worktree : un worktree Git créé à partir de votre checkout local dans l’application de bureau ChatGPT.
  • Handoff : le processus qui déplace un chat entre Local et Worktree. Codex gère les opérations Git nécessaires pour transférer 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 des tâches en file d’attente en arrière-plan tout en restant concentré sur votre travail au premier plan.
  3. Déplacez ultérieurement un chat vers Local lorsque vous êtes prêt à examiner ou tester le travail, ou à collaborer plus directement.

Bien démarrer

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 saisie. Vous pouvez également choisir un environnement local afin d’exécuter des scripts de configuration pour le worktree.

  2. Sélectionnez la branche de départ

    Sous la zone de saisie, choisissez la branche Git sur laquelle fonder le worktree. Il peut s’agir de votre branche main / master, d’une branche de fonctionnalité ou de votre branche actuelle contenant 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 dans un état « detached HEAD ».

  4. Choisissez où poursuivre votre 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 votre chat et votre code afin que vous puissiez continuer dans l’autre checkout.

Travailler entre Local et Worktree

Les worktrees présentent une apparence et un fonctionnement très proches de votre checkout local. La différence tient à leur place dans votre flux de travail. 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 arrière-plan, Handoff gère les opérations Git nécessaires pour transférer le travail entre deux checkouts en toute sécurité. Ce point est important, car Git n’autorise l’extraction d’une branche qu’à 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 convient particulièrement 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 d’environnement local.
  2. Transférer le chat vers Local. Choisissez ce parcours lorsque vous souhaitez ramener le chat au premier plan, par exemple pour examiner les modifications dans votre IDE habituel ou parce que vous ne pouvez exécuter qu’une seule instance de votre application.

Option 1 : travailler dans le worktree

Si vous souhaitez conserver vos modifications et travailler exclusivement dans le worktree, transformez ce dernier en branche à l’aide du bouton Create branch here dans l’en-tête du chat.

Vous pouvez ensuite valider 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 « Open » de l’en-tête, utiliser le terminal intégré ou tout autre outil dont vous avez besoin depuis le répertoire du worktree.

Vue d’un chat dans un worktree avec les commandes de branche et les détails du worktree (mode clair)

N’oubliez pas que si vous créez une branche dans un worktree, vous ne pouvez l’extraire dans aucun autre worktree, y compris dans votre checkout local.

Option 2 : transférer un chat vers Local

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

Ce parcours est particulièrement adapté si vous souhaitez consulter 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 chat conserve le même worktree associé au fil du temps. Si vous retransférez ultérieurement le chat vers un worktree, Codex le replace dans ce même environnement d’arrière-plan afin que vous puissiez reprendre là où vous vous étiez arrêté.

Boîte de dialogue Handoff déplaçant un chat d’un worktree vers Local (mode clair)

Vous pouvez également procéder dans l’autre sens. Si vous travaillez déjà dans Local et souhaitez libérer le premier plan, utilisez Hand off pour déplacer le chat vers un worktree. Cette option est utile lorsque vous souhaitez que Codex continue de travailler en arrière-plan pendant que vous reportez votre attention sur une autre tâche en local.

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

Détails avancés

Worktrees gérés par Codex et permanents

Par défaut, les chats utilisent un worktree géré par Codex. Ces worktrees sont conçus pour être légers et temporaires. Un worktree géré par Codex est généralement réservé à un seul chat, et Codex replace ce chat dans le même worktree si vous l’y 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 en tant que 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 tâche. 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 : les fichiers suivis sont donc déjà présents. Si votre dépôt ignore des fichiers de configuration locale 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 qui correspondent à .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. Vous n’avez donc pas besoin 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’application de bureau ChatGPT, mais pas aux worktrees distants ni aux worktrees Git que vous créez vous-même depuis la ligne de commande.

Limites 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 Create branch here. Vous souhaitez maintenant la tester 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 devriez extraire une branche autre que feature/a dans le worktree.

Si vous prévoyez d’extraire la branche en local, 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.

Pourquoi cette limite existe-t-elle ?

Git empêche l’extraction simultanée d’une même branche dans plusieurs worktrees, car une branche représente une référence mutable unique (refs/heads/<name>) dont la signification est « l’état actuellement extrait » d’une arborescence de travail.

Lorsqu’une branche est extraite, Git considère que son HEAD appartient à ce worktree et s’attend à ce que des opérations comme les commits, les réinitialisations, les rebases et les fusions fassent avancer cette référence de manière clairement définie et séquentielle. Autoriser plusieurs worktrees à extraire simultanément la même branche créerait des ambiguïtés et des conditions de concurrence quant au worktree dont les opérations mettent à jour la référence de branche, ce qui pourrait entraîner la perte de commits, des index incohérents ou une résolution des conflits ambiguë.

En appliquant la règle d’une branche par worktree, Git garantit que chaque branche dispose d’une seule copie de travail faisant autorité, tout en permettant aux autres worktrees de référencer les mêmes commits en toute sécurité au moyen de detached HEADs ou de branches distinctes.

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’application de bureau ChatGPT essaie de maintenir le nombre de worktrees dans 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 de l’espace disque.

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

  • 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 lorsque :

  • Vous archivez le chat associé
  • Codex doit supprimer d’anciens worktrees pour respecter la limite que vous avez 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 permettra de le restaurer.

Questions fréquentes

Puis-je choisir l’emplacement de création des worktrees ?

Oui. Par défaut, Codex crée les worktrees gérés sous $CODEX_HOME/worktrees. Pour choisir un autre emplacement, ouvrez Settings > Worktrees et modifiez Worktree root.

Puis-je déplacer une conversation entre Local et Worktree ?

Oui. Utilisez Hand off dans l’en-tête de la conversation pour déplacer celle-ci entre votre copie de travail locale et un worktree. Codex effectue les opérations Git nécessaires pour déplacer la conversation en toute sécurité entre les environnements. Si vous retransférez ultérieurement une conversation vers un worktree, Codex la renvoie vers le même worktree associé.

Qu’advient-il des conversations si un worktree est supprimé ?

Les conversations peuvent rester dans votre historique même si le répertoire du worktree sous-jacent est supprimé. Pour les worktrees gérés par Codex, Codex enregistre un instantané avant de supprimer le worktree et vous propose de le restaurer si vous rouvrez la conversation associée. Les worktrees permanents ne sont pas automatiquement supprimés lorsque vous archivez leurs conversations.