OpenCode Worktree : séparer les tâches de code avec Git

Un Git worktree est un autre répertoire de travail relié au même dépôt. Le checkout principal peut rester sur main, tandis qu’un dossier voisin utilise work/auth. Les fichiers et la branche courante sont distincts, mais Git partage les objets et l’historique : un clone complet par tâche n’est généralement pas nécessaire.

Ce flux ne nécessite pas de mode worktree spécial dans OpenCode. Lancez la CLI depuis le nouveau dossier, qui devient le contexte du projet. Les réglages globaux peuvent toujours s’appliquer, mais les fichiers non suivis et l’environnement local ne sont pas copiés automatiquement.

Commencez par vérifier le checkout courant. Un point de départ propre aide à distinguer les changements de la tâche principale de ceux de la nouvelle branche. Depuis la racine du dépôt, créez une branche et son worktree dans un dossier voisin, à l’extérieur du dépôt d’origine.

L’exemple crée work/auth au commit courant et le place dans ../app-auth. Si la branche existe déjà, vérifiez qu’un autre worktree ne l’utilise pas avant de la reprendre. Git empêche généralement de checkout une même branche dans plusieurs worktrees liés.

Lancez ces commandes depuis la racine du dépôt principal. La branche démarre au commit courant.

git status --short --branch
git worktree add -b work/auth ../app-auth
cd ../app-auth
opencode
git worktree list
git -C ../app-auth status --short --branch

Après cd ../app-auth, lancez opencode depuis ce shell. Le répertoire courant est la frontière importante : ouvrez un terminal ou une session par worktree, puis vérifiez la racine du projet avant d’autoriser des modifications. Une première demande en lecture seule peut résumer la branche et les fichiers à inspecter.

Donnez à chaque session une tâche précise et notez sa branche. L’une peut modifier les tests d’authentification, l’autre la documentation. Évitez que deux sessions modifient le même fichier ou le même dossier généré. Des répertoires distincts réduisent les collisions, mais ne coordonnent pas automatiquement les agents.

Le worktree sépare les fichiers suivis par Git et l’index, mais ce n’est ni un conteneur ni une frontière de sécurité. Une base locale, un serveur de test, un cache, un projet Docker ou un compte externe peut rester partagé. Si nécessaire, séparez le schéma, le port, le nom du projet ou utilisez un environnement jetable.

Git récupère les fichiers suivis du commit choisi. Les fichiers .env, certificats, caches et résultats ignorés ne sont pas garantis dans le nouveau worktree. Recréez seulement l’environnement nécessaire, chargez les secrets via le mécanisme approuvé et vérifiez git status --short --branch avant et après le travail.

Relisez la branche du worktree comme un changement indépendant. Inspectez git diff, lancez les vérifications du projet dans ce dossier et confirmez que seuls les fichiers attendus sont présents. Après les tests, fusionnez ou rebasez selon le processus de l’équipe. Les changements n’apparaissent pas dans un autre checkout avant le partage des commits.

Avant la suppression, repérez les modifications non validées et décidez de les commit, stash ou conserver. git worktree remove ../app-auth supprime un checkout propre ; Git refuse s’il reste des changements, sauf option forcée. N’utilisez pas la force comme nettoyage normal. git worktree prune retire les enregistrements obsolètes, pas les worktrees actifs.

Choisissez un worktree pour séparer des branches, des snapshots de fichiers ou une limite de revue qui doit rester ouverte plusieurs jours. Pour une enquête en lecture seule ou qui doit voir les fichiers non commités, une autre session dans le même checkout est plus simple. Pour des tâches séquentielles, changez simplement de branche.

Le worktree ajoute la gestion des noms de branches, dépendances, services, tests, fusion et nettoyage. Si deux agents modifient les mêmes fichiers, l’intégration finale peut devenir plus difficile. Séparez d’abord les changements ou exécutez ces modifications dans l’ordre.

Si git worktree add indique que la branche est déjà utilisée, consultez git worktree list, puis créez une branche distincte ou revenez au worktree existant. Si OpenCode affiche des fichiers inattendus, vérifiez le chemin du terminal et la racine du projet avant de changer la configuration. Les fichiers ignorés ne font pas partie du checkout.

Si les tests se gênent entre sessions, cherchez hors de Git : bases, ports, dossiers temporaires, générateurs et caches partagés. Si la suppression est bloquée, exécutez git status dans ce worktree et préservez les changements utiles. Gardez le checkout principal disponible pour intégrer le travail.