Aller au contenu

Créer et détruire un worktree

Vous êtes développeur·se sur Kirexo et vous voulez travailler sur plusieurs tickets en parallèle, chacun avec sa propre stack : son projet Compose, son réseau, son image, sa base de données et ses trois URLs. Cette recette couvre le cycle complet — créer, travailler, lister, détruire, faire le ménage — avec les six cibles castor wt:*.

Quand la stack d'un worktree refuse de monter, la marche à suivre est dans Réparer un worktree dont la stack ne démarre plus.

Le détail des options de chaque cible est dans Commandes Castor — Worktrees ; cette page décrit le parcours.

Prérequis

  • Un terminal côté hôte, ouvert à la racine du dépôt principal (le dossier qui contient le .git répertoire).
  • Docker démarré.
  • castor proxy:up joué au moins une fois sur le poste, et castor cert:trust pour que la CA du proxy soit reconnue. Les trois URLs d'un worktree passent alors sans avertissement.
  • Une branche à jour : le worktree hérite des fichiers de la branche depuis laquelle il est créé (voir Mon worktree démarre sans alias ni confinement).

Les six cibles wt:* sont hôte-only

wt:up, wt:shell (alias wt:bash), wt:claude, wt:list, wt:destroy et wt:gc pilotent Docker et git : lancées depuis le conteneur, elles refusent de tourner et rappellent la commande à taper côté hôte — à la racine du dépôt principal, ou depuis le répertoire du worktree pour wt:shell et wt:claude. Il n'y a pas de socket Docker dans le conteneur, c'est un invariant du confinement.

Depuis l'intérieur, il vous reste castor doctor, castor doctrine:migrate, castor fixtures:load et castor all.

Étape 1 — Créer et démarrer le worktree

castor wt:up 185

Les trois formes 185, #185 et ticket-185 désignent le même worktree, normalisé en ticket-185.

Au premier appel, la cible :

  1. crée le worktree dans <parent du dépôt principal>/kirexo-worktrees/ticket-185 — à côté du dépôt principal, jamais dessous ; la racine se change avec KIREXO_WORKTREES_DIR ;
  2. choisit la branche : le nom du worktree (ticket-185), sauf si une branche 185-* existe déjà en local ou sur origin — auquel cas elle est réutilisée (une branche distante est suivie, pas recréée). Si plusieurs branches correspondent, la cible s'arrête en les listant : tranchez avec --from. Aucun appel à l'API GitLab n'est fait, la création fonctionne hors ligne ;
  3. démarre le proxy hôte et la stack mutualisée kirexo-shared (les deux sont idempotents et partagés par tous les worktrees) ;
  4. réconcilie les fichiers de la stack et construit l'image kirexo-dev-local:ticket-185 ;
  5. installe les dépendances Composer dans un conteneur jetable — après avoir amorcé vendor/ depuis le dépôt principal — puis démarre les conteneurs ;
  6. installe les assets front — importmap:install et tailwind:build — une fois la stack debout ;
  7. applique les migrations Doctrine et, parce que la base est vierge, charge les fixtures ;
  8. affiche les trois URLs.

Un worktree neuf n'a ni vendor/, ni assets : wt:up s'en charge

vendor/, assets/vendor/ et var/tailwind/ sont gitignorés — un checkout neuf n'en a aucun, et le vendor/ construit dans l'image est masqué par le bind .:/app. Les étapes 5 et 6 comblent ce trou : aucun geste manuel n'est attendu de vous, ni castor install, ni docker compose run.

Pour éviter de retélécharger tout vendor/ à travers le proxy sortant, wt:up commence par le copier depuis le dépôt principal quand le worktree n'en a aucun. La ligne + amorce vendor (vendor/ amorcé depuis le dépôt principal) le signale, et la copie est quasi instantanée — sans coût disque — sur un système de fichiers copy-on-write (btrfs, xfs). composer install est joué derrière dans tous les cas : c'est lui qui fait foi sur la correspondance avec composer.lock, la copie ne fait que raccourcir son travail.

Comptez tout de même plusieurs minutes au premier appel — le téléchargement du binaire Tailwind et la première compilation du CSS restent à faire, et l'amorce n'a pas lieu quand le dépôt principal n'a pas de vendor/ exploitable, ce que wt:up annonce par une ligne = amorce vendor (pas d'amorce : …). La sortie de Composer est retenue et n'apparaît qu'en cas d'échec ; wt:up annonce l'attente pour que le silence ne se lise pas comme un blocage.

Aux appels suivants, ces deux étapes sont des = : elles ne se redéclenchent que si composer.lock, importmap.php ou assets/styles/app.css sont plus récents que ce qu'ils ont produit.

Service URL
Application https://app.ticket-185.localhost
Mailpit https://mailpit.ticket-185.localhost
Documentation (mkdocs) https://docs.ticket-185.localhost

Les trois portent un préfixe de service, y compris l'application. Ce n'est pas décoratif : un nom d'un seul label sous .localhost se ferait servir un certificat wildcard qu'aucun navigateur n'accepte — cf. Pourquoi tout nom servi a au moins deux labels.

Les options utiles au moment de la création :

castor wt:up 212 --from=185-editeur-de-blocs   # partir d'une autre branche que main
castor wt:up 202 --from=202-fix-chromium-pin   # trancher entre deux branches du ticket 202
castor wt:up 212 --profile=full                # profil de ressources, mémorisé
castor wt:up 212 --no-build                    # ne pas (re)construire l'image

--from n'agit qu'à la création : sur un worktree existant, wt:up ne fait ni checkout, ni pull, ni rebase — il ne touche jamais à votre travail. À la création, il a deux rôles selon la situation : point de départ quand la branche doit être créée, et arbitrage quand plusieurs branches <numéro>-* correspondent au ticket. Dans ce second cas, la valeur doit figurer parmi les branches listées par le message d'erreur — sinon elle ne tranche rien, et la cible le dit. Détail : Les deux rôles de --from.

--fixtures purge la base du worktree

Les fixtures ne sont chargées que sur une base vierge — aucune migration appliquée, mesuré dans le conteneur avant le migrate — ou sur castor wt:up 185 --fixtures. doctrine:fixtures:load sans --append purge la base : la rejouer à chaque wt:up détruirait le travail en cours à chaque redémarrage de la stack.

Conséquence pratique : un worktree dont le premier wt:up a échoué reçoit bien ses fixtures au passage suivant, sans rien demander. Le détail des quatre cas est dans Quand les fixtures sont chargées.

wt:up est le seul geste qui crée un worktree : c'est aussi la seule cible qui accepte --profile, --from, --fixtures et --no-build. castor wt:shell et castor wt:claude ne créent rien — elles visent le worktree du répertoire courant, cf. Étape 3 — mais démarrent sa stack si elle ne répond pas.

wt:up regarde d'abord d'où vous le lancez

Avant même d'annoncer le worktree, la cible contrôle son point de départ, et vous propose — dans un terminal seulement — de partir d'un main à jour. Trois situations, une question au plus à chaque fois :

  • lancé depuis un worktree : aller d'abord dans le dépôt principal ? Un « oui » rend la main avec la commande complète à rejouer là-bas, options comprises ; un « non » enchaîne sans un mot sur main ;
  • lancé depuis le dépôt principal, hors de main : basculer sur main ? La bascule est tentée pour de vrai ; si git refuse, sa sortie et les remèdes s'affichent, et wt:up continue quand même ;
  • lancé depuis le dépôt principal, sur un main en retard : mettre main à jour ? (git merge --ff-only origin/main).

Rien n'est imposé : le worktree se crée dans tous les cas, et le contrôle se tait hors d'un terminal — CI, hook, session d'agent, castor wt:up 185 -n. Il se contente alors de rapporter l'écart par une ligne !. Détail : Le contrôle du point de départ.

Étape 2 — Relancer wt:up : lire le rapport de réconciliation

castor wt:up 185 est idempotent : relancez-le pour démarrer une stack arrêtée, après un git pull qui change le Dockerfile, ou simplement en cas de doute. Chaque appel réconcilie l'environnement du worktree et affiche une ligne par élément :

Préfixe Sens
= inchangé
~ réconcilié (l'élément existait, il a été remis à l'état attendu)
+ créé
! divergence signalée mais non corrigée — à traiter à la main

Ce qui est réconcilié à chaque appel :

  • le worktree git — recréé si son répertoire a disparu (voir J'ai supprimé le répertoire du worktree à la main) ;
  • .env.worktree — les 16 clés du contrat (cf. Variables de worktree) ; vos clés hors contrat et vos XDEBUG_CLIENT_PORT / REDIS_DB_INDEX déjà alloués sont conservés ;
  • le lien var/claude vers l'espace de travail partagé du dépôt principal (voir ci-dessous) — un var/claude local non vide est conservé et signalé (!), jamais écrasé ;
  • la whitelist locale infra/firewall/whitelist.local.txt du worktree, copiée depuis le .dist si elle manque — elle sert de substrat au bind :ro de l'invariant C4, pas à alimenter le proxy, qui lit celle du dépôt principal (pourquoi) ;
  • la conf proxy du worktree, avec un proxy:reload seulement si elle a changé ;
  • l'image kirexo-dev-local:ticket-185, reconstruite si elle est absente ou plus ancienne que le Dockerfile ou le compose.override.yaml ;
  • .claude/settings.local.json, généré s'il est absent et aligné s'il existe (~) : la clé permissions.defaultMode est retirée quand elle vaut bypassPermissions — Claude Code l'ignore, le mode vient de la ligne de commande de castor wt:claude —, le consentement skipDangerousModePermissionPrompt est posé, et vos autres réglages sont préservés (serveurs MCP, hooks, modèle, autorisations). Un defaultMode que vous auriez mis à plan n'est pas touché. Détail : wt:up, tableau de réconciliation ;
  • les dépendances Composer, réinstallées si vendor/autoload_runtime.php est absent ou plus ancien que composer.lock ;
  • les assets front, réinstallés si assets/vendor/ ou le CSS compilé sont plus anciens que importmap.php et assets/styles/app.css — ou dès qu'une installation Composer vient d'avoir lieu ;
  • les migrations Doctrine, toujours ; les fixtures, jamais (sauf base vierge ou --fixtures).

Au second appel, tout doit être = : c'est la preuve à l'œil nu que rien n'a bougé.

Dans un worktree, on démarre la stack avec wt:up, pas avec docker:up

compose.worktree.yaml — le fichier qui monte le git common dir et le var/claude partagé, et qui injecte WT dans le conteneur — n'est jamais auto-découvert par Docker Compose : une cible doit l'empiler explicitement. wt:up le fait ; castor docker:up non. Lancé depuis le répertoire d'un worktree, docker:up démarre donc bien sa stack (le projet Compose vient de .env.worktree), mais sans ce montage : plus aucune commande git ne fonctionne dans le conteneur, et rien ne le signale. Le remède est un castor wt:up <ticket>, qui recrée les conteneurs avec le bon modèle.

Étape 3 — Travailler dans le worktree

Ouvrez le répertoire du worktree dans votre IDE, ou entrez dans son conteneur. Le geste commence par un cd : les deux cibles n'ont pas d'argument, elles visent le worktree du répertoire courant.

cd ../kirexo-worktrees/ticket-185
castor wt:shell         # un shell dans le conteneur php de ce worktree
castor wt:bash          # alias strictement équivalent

La résolution remonte l'arborescence, donc n'importe quel sous-dossier fait l'affaire :

cd ../kirexo-worktrees/ticket-185/src
castor wt:shell         # vise ticket-185, lu dans le .env.worktree en remontant

Depuis le dépôt principal, ces cibles s'arrêtent

wt:shell et wt:claude acceptaient un ticket et visaient alors n'importe quel worktree depuis n'importe où. Ce n'est plus le cas : c'est une capacité en moins, et son remplaçant est le cd ci-dessus. Lancées hors d'un worktree, elles listent les worktrees réels avec leur chemin, prêt à coller, et sortent en 1.

En échange, une typo de numéro ne crée plus rien : il n'y a plus de numéro à taper. Détail : Le worktree visé.

Ces deux cibles démarrent la stack si elle ne répond pas

Ni wt:shell ni wt:claude n'exigent une stack en marche. Quand le conteneur php ne répond pas, elles lancent castor wt:up sur le worktree courant, une seule fois, en l'annonçant à l'écran — comptez une minute, le temps de la réconciliation, des migrations et du healthcheck. Elles ne créent en revanche aucun worktree : on ne peut pas être dans le dossier d'un worktree qui n'existe pas. La création reste castor wt:up <ticket> — Étape 1 —, que la cible vous proposera de jouer depuis le dépôt principal si vous l'appelez d'un autre worktree.

Pour désactiver l'auto-démarrage — typiquement quand vous savez la stack cassée et voulez le conteneur jetable sans attendre :

KIREXO_WT_NO_AUTO_UP=1 castor wt:shell

Détail : Le démarrage automatique de la stack.

Les cibles applicatives habituelles — castor console, castor test:unit, castor all — visent la stack du worktree, qui a sa propre base.

wt:shell plutôt que docker:sh, même quand tout va bien

castor docker:sh fait un exec sur le projet Compose auto-découvert : il exige un conteneur vivant. C'est exactement le geste qui échoue quand la stack est cassée. castor wt:shell tente un démarrage quand le conteneur php ne répond pas, puis bascule sur un conteneur jetable, même image et même code, s'il ne répond toujours pas. Elle empile par ailleurs les trois fichiers Compose avec l'environnement du .env.worktree, donc elle vise le bon projet depuis n'importe quel sous-dossier. Détail : castor wt:shell, parcours de réparation : Réparer un worktree dont la stack ne démarre plus.

Ouvrir une session Claude Code dans le worktree

cd ../kirexo-worktrees/ticket-185
castor wt:claude                   # session neuve dans ce worktree
castor wt:claude --resume          # exécute claude --resume dans le conteneur

La cible lance claude dans le conteneur php du worktree et lui transmet tous ses tokens tels quels. Trois points à retenir au moment de taper la commande :

  • aucune contrainte de position : castor wt:claude --resume est la forme normale. En contrepartie, un premier token en forme de ticket (215, #215, ticket-215) est refusé — sans ce garde-fou, il partirait à claude comme prompt, en silence ;
  • --help, -v et -q sont des options de Castor avant d'être celles de claude. castor wt:claude --help affiche l'aide de Castor ; pour celle de Claude Code, passez par castor wt:shell puis claude --help ;
  • wt:claude n'a pas de repli en conteneur jetable. Si le conteneur php ne répond toujours pas après le wt:up qu'elle a lancé, elle s'arrête et vous renvoie vers castor wt:shell, dont le conteneur jetable est la seule porte d'entrée quand la stack est cassée à ce point.

Le code de sortie de claude est propagé, donc castor wt:claude -p "…" s'utilise dans un script. Le détail complet est dans castor wt:claude ; les conversations sont partagées entre tous les worktrees, ce qui est expliqué dans Pourquoi l'espace Claude est commun à tous les worktrees.

castor test:e2e ramène la base du worktree à l'état fixtures

Les tests E2E tapent sur le serveur de dev et rechargent donc les fixtures en base dev avant chaque run, sans --append : la purge est incluse. Un E2E lancé dans un worktree efface les données que vous y aviez saisies. Ce n'est pas un effet de bord de wt:up, c'est le comportement documenté de castor test:e2e.

git fonctionne dans le conteneur — et ce que ça implique

Le fichier .git d'un worktree n'est pas un répertoire mais un pointeur d'une ligne vers <dépôt principal>/.git/worktrees/<worktree>, en chemin absolu côté hôte. Pour que git status, git add et git commit fonctionnent depuis le conteneur, le git common dir du dépôt principal y est monté au même chemin absolu, en lecture-écriture — un git commit écrit l'index du worktree, mais aussi les objets et refs/heads/<branche>, qui vivent dans le common dir partagé.

Deux conséquences, assumées et sans contre-mesure dans le code :

  • les refs des autres branches sont accessibles en écriture depuis n'importe quel worktree : le common dir est partagé. Un agent, ou une commande maladroite (git branch -f, git update-ref, git gc), peut donc affecter le travail d'un autre worktree ;
  • l'historique des autres branches reste lisible : git show autre-branche:fichier, git log origin/main et les git diff inter-branches fonctionnent depuis le conteneur, alors même que le système de fichiers du worktree voisin est invisible (ls <autre worktree> rend ENOENT).

L'invariant de confinement C8 se formule donc « aucun accès au système de fichiers des autres worktrees », jamais « aucun accès au code des autres branches ». Le contrat complet et ses limites vivent dans .claude/skills/_shared/confinement.md ; le raisonnement est dans Modèle de menace et contrat de confinement.

Le git push fonctionne lui aussi depuis le conteneur, sous réserve du garde-fou pre-push qui refuse main, les branches d'intégration et les tags : Pousser sur GitLab depuis un worktree.

Un espace de travail partagé avec le dépôt principal

var/claude d'un worktree est un lien vers <dépôt principal>/var/claude, monté au même chemin absolu dans le conteneur. Un worktree neuf y trouve donc immédiatement le cadrage de l'étape en cours, les specs de lots et les scripts déjà écrits, au lieu d'un dossier vide.

Deux conséquences pratiques :

  • ce que vous y écrivez est visible partout, y compris depuis l'hôte et depuis les autres worktrees. C'est voulu — les scripts de ship sont écrits dans le conteneur et lancés depuis l'hôte — mais cela signifie qu'un rm maladroit y porte au-delà du worktree courant ;
  • l'état d'une session reste local : checklist de clôture, quota de fichiers PHP, compteur de blocage et checkpoints des sous-agents vivent sous var/claude/.session/<worktree>/. Sans ce cloisonnement, deux worktrees ouverts en parallèle se corrompraient mutuellement leur état.

Le raisonnement est dans Pourquoi l'agent pousse lui-même, et ce qui le retient.

Étape 4 — Voir où on en est : castor wt:list

castor wt:list
castor wt:list --no-stats --no-fetch   # plus rapide : sans docker stats, sans git fetch

Une ligne par worktree lié (le dépôt principal n'est pas listé, ce n'est pas un worktree) :

Colonne Lecture
ticket Nom du worktree. Un * marque le worktree par défaut du proxy (voir ci-dessous).
branche Branche checkoutée, ou (détaché).
état up (n/n, m healthy), partiel (n/m) ou arrêté. n compte les services vivants, m ceux que les fichiers Compose du worktree déclarent : un php mort donne bien partiel. Un ? final signale un dénombrement non fiable, un ⚠ un worktree dont la configuration n'est pas celle attendue — voir ci-dessous.
URLs Les trois URLs, ou — si la stack est arrêtée.
âge Ancienneté des métadonnées git du worktree, ou ⚠ répertoire absent.
RAM Somme de la mémoire des conteneurs du projet. Vide avec --no-stats.
mergée ? oui (il y a 12 j), oui, squash (…), non, ou ? quand l'information n'a pas pu être obtenue.
core ? Coredumps trouvés à la racine du worktree — ils pèsent plusieurs gigaoctets et passent inaperçus.

Un projet Compose kirexo-* sans worktree correspondant est un résidu : il est signalé sous le tableau, avec la commande de nettoyage.

Un état suffixé ? : le total n'est pas fiable

up (2/2) ? ou partiel (2/3) ? signifie que docker compose config --services a échoué sur ce worktree — presque toujours un .env.worktree antérieur à une variable devenue requise. Le total ne compte alors que les conteneurs qui existent encore, et peut être sous-évalué. Le pied de tableau nomme les worktrees concernés et donne le remède :

castor wt:up <ticket>

Il réconcilie le .env.worktree au passage, et le ? disparaît. Détail : castor wt:list.

Un état suffixé ⚠ : l'état affiché n'est pas mesurable

arrêté ⚠ signale un worktree dont le .env.worktree est absent, ou qui déclare un autre projet Compose que kirexo-<worktree>. Dans les deux cas l'état affiché ne veut rien dire : sans le fichier, la sonde ne peut rien lire ; avec un nom divergent, elle interroge kirexo-<worktree> pendant que la stack tourne peut-être sous le nom déclaré. Le pied de tableau nomme le worktree, la valeur déclarée et le remède — castor wt:up <ticket> régénère le fichier. Détail : Le projet Compose visé par les cibles de worktree.

Qui sert app.demo.localhost ?

Les domaines de site publics — app.demo.localhost, celui du site de démonstration, en tête — ne sont pas des URLs d'infrastructure : ils sont résolus en base par le multi-tenant, donc servis par un seul worktree à la fois, le worktree par défaut du proxy.

Hors worktree, c'est le dépôt principal, traité comme un worktree de nom figé main. Le premier castor wt:up prend la main et wt:list le marque d'un * ; les wt:up suivants ne volent pas sa place ; un castor wt:destroy du porteur rend la main à main. Pour savoir qui sert quoi à un instant donné : castor proxy:status. Le raisonnement est dans Les domaines de site publics et le worktree par défaut.

Étape 5 — Détruire un worktree

castor wt:destroy 185

La cible refuse de détruire un worktree qui porte du travail non sauvegardé — fichiers modifiés ou commits non poussés — puis demande confirmation. Deux options pour les cas particuliers :

castor wt:destroy 185 --force   # passe outre les garde-fous de perte de travail
castor wt:destroy 185 --yes     # ne demande pas de confirmation

Depuis le dossier du worktree, la commande se relance seule

Détruire un worktree sans en sortir fonctionne, et c'est le cas courant : on finit un ticket, on est dans son répertoire. La cible s'en aperçoit et relance la destruction depuis le dépôt principal — elle ne peut pas effacer le vendor/ dont elle a besoin pour finir de s'exécuter. Elle l'annonce avant de toucher à quoi que ce soit :

  ⟳ relance depuis /home/…/kirexo — ce worktree porte le vendor de la commande

La suite s'affiche alors dans une section Castor ([1] castor wt:destroy … success after 12s) au lieu du flux direct, parce qu'elle vient d'un sous-processus : c'est normal. La confirmation n'est pas redemandée, --force est conservé, et le code de sortie reste celui de la destruction. Détail : castor wt:destroy.

Hors d'un terminal, --yes n'est plus optionnel

Dans un script, un hook ou un job CI, la cible ne peut pas poser sa question : elle sort en 1 et imprime la commande à retaper, --yes (et --force s'il avait été passé) inclus. Elle n'attend jamais une réponse que personne ne donnera. Cf. Les confirmations hors terminal.

Un worktree cassé se détruit quand même

wt:destroy est la seule cible qui continue quand .env.worktree a disparu : elle avertit, puis détruit le projet kirexo-<worktree>. Refuser interdirait le seul geste qui nettoie un worktree dans cet état. Contrôlez ensuite l'absence de résidus avec docker compose ls et castor wt:list — cf. castor wt:destroy.

Des services mutualisés peuvent être recréés au passage

Les stacks kirexo-shared et kirexo-proxy sont créées une fois pour le poste, depuis le répertoire de celui qui les a démarrées le premier — souvent un worktree. Leurs montages y sont figés en chemins absolus : détruire ce répertoire les casserait. Avant de retirer le worktree, wt:destroy défait ce parentage et l'annonce :

⟳ kirexo-shared : egress-proxy monté(s) depuis ce worktree — recréation depuis le dépôt principal
  ✓ vérifié : plus aucun montage sur le worktree, service(s) en marche
ℹ kirexo-shared : redis, rabbitmq, typesense a/ont été lancé(s) depuis ce worktree, sans bind dessus — laissé(s) tel(s) quel(s)
  • la ligne ⟳ recrée le service : il montait un dossier du worktree, il serait mort au redémarrage suivant. Si egress-proxy en fait partie, la sortie réseau est coupée quelques secondes pour tous les worktrees — un composer install en cours ailleurs échoue et doit être relancé ;
  • la ligne ℹ ne touche à rien : ces services tournent toujours, ils ont seulement été lancés depuis ce worktree. Jusqu'à leur prochaine recréation, un docker compose -p kirexo-shared ps tapé sans -f depuis un autre répertoire reste en erreur ; avec -f compose.shared.yaml, il répond normalement.

Détail des deux signaux : Le re-parentage des projets singletons.

La base Postgres du worktree est supprimée

La destruction commence par un docker compose down -v : conteneurs, réseau et volumes du projet du worktree disparaissent. Tout ce que vous aviez saisi dans cette base est perdu. Si le down échoue (Docker arrêté, par exemple), rien d'autre n'est touché : le worktree et son .env.worktree sont conservés, et vous pouvez relancer la commande.

Ce que wt:destroy ne supprime pas, volontairement :

  • la branche git, locale comme distante — une branche est du travail, pas un artefact ;
  • les couches de l'image : seul le tag kirexo-dev-local:<worktree> est retiré. Les couches sont dédupliquées par digest et servent aux autres worktrees ;
  • le proxy hôte (castor proxy:down est un geste séparé) et la stack mutualisée kirexo-shared : les descendre couperait la sortie réseau et le routage de tous les autres worktrees ;
  • les volumes qui n'appartiennent pas au projet du worktree — down -v ne touche que les siens ;
  • le contenu de var/claude — seul le lien posé dans le worktree disparaît. Les specs, scripts et rapports vivent dans le dépôt principal et survivent à la destruction (cf. Un espace de travail partagé avec le dépôt principal).

En fin de course, la cible vérifie l'absence de résidus (conteneurs, volumes, réseau, conf proxy, répertoire) et sort en erreur s'il en reste, avec la liste. Relancer la commande est sans danger : chaque étape est un no-op quand elle est déjà faite.

Étape 6 — Faire le ménage : castor wt:gc

castor wt:gc            # branches mergées depuis plus de 7 jours
castor wt:gc --days=0   # tout ce qui est mergé

wt:gc propose et n'exécute rien : il affiche les worktrees dont la branche est mergée depuis assez longtemps, puis les commandes castor wt:destroy … à copier. À vous de décider.

Deux points à connaître :

  • le squash-merge est géré : une MR squashée réécrit l'historique en un commit dont la branche n'est pas ancêtre de main. Sans un second chemin de détection via glab, aucun worktree ne serait jamais proposé dès qu'une MR est squashée ;
  • hors ligne, glab en échec rend ?, jamais « non mergée » : aucune destruction n'est proposée sur une information qu'on n'a pas pu obtenir. --no-fetch évite l'appel réseau à git fetch.

Dépannage

Mon worktree démarre sans alias ni confinement

Un worktree est un checkout distinct : il porte les fichiers de sa branche. Créé avec --from sur une branche antérieure à la mise en place des worktrees (ou jamais rebasé depuis), il n'a ni compose.worktree.yaml, ni les alias réseau et le internal: true de compose.override.yaml. Sa stack démarrerait donc sans le montage du git common dir — aucune commande git dans le conteneur — et sans confinement réseau, silencieusement.

wt:up détecte le cas et s'arrête en réclamant un rebase. Il ne rebase jamais de lui-même : votre branche est votre travail.

Le message nomme la base à utiliser, et il la mesure : la cible cherche la première référence connue du dépôt qui porte réellement compose.worktree.yaml, en essayant origin/main puis main avant les autres. Tant que le lot qui a créé ce fichier n'est pas mergé, origin/main ne le porte pas — un remède qui la nommerait en dur enverrait dans le mur.

git -C <chemin du worktree> rebase <la référence indiquée par le message>
castor wt:up <ticket>                            # la stack repart avec le bon modèle

C'est une limite inhérente à git worktree, pas un défaut de la cible.

Le premier wt:up s'arrête sur l'installation des dépendances

Sur un worktree neuf, wt:up installe les dépendances Composer avant de démarrer la stack. S'il n'y arrive pas, il s'arrête là plutôt que de laisser FrankenPHP boucler en crash : le message affiche la sortie de Composer, qui porte la cause réelle.

Deux causes couvrent la quasi-totalité des cas :

  • un domaine manque à l'allowlist du proxy sortant — la trace contient CONNECT tunnel failed, response 403. Confirmez avec castor firewall:status, puis ouvrez le domaine. Si le 403 tombe sur le téléchargement du binaire Tailwind, lisez Un téléchargement refusé laisse un artefact vide : un résidu de 0 octet fait réapparaître la même erreur même après l'ouverture du domaine ;
  • composer.lock diverge de composer.json — la trace le dit explicitement. Le remède se joue dans le dépôt principal (castor install), pas dans le worktree.

Rejouer l'installation à la main, sans passer par toute la séquence — le message affiché par wt:up donne la ligne complète, prête à coller, avec le nom de projet et les fichiers Compose de votre worktree :

cd <chemin du worktree>
docker compose -p kirexo-<worktree> \
  -f compose.yaml -f compose.override.yaml -f compose.worktree.yaml \
  run --rm --no-deps php composer install

Les deux morceaux ajoutés ne sont pas décoratifs : sans le -p, la commande crée un conteneur dans un projet déduit du nom du répertoire (Le projet Compose visé par les cibles de worktree) ; sans les -f, compose.worktree.yaml n'est pas empilé — Compose ne l'auto-découvre jamais — et le conteneur obtenu perd le montage du git common dir. En profil full, wt:up ajoute -f compose.full.yaml.

wt:up avertit que l'amorce de vendor/ a échoué

Il n'y a rien à faire. L'amorce est une optimisation : quand la copie échoue — disque plein, permissions, vendor/ du dépôt principal modifié pendant la copie par un castor install concurrent —, wt:up l'annonce et enchaîne sur l'installation complète, comme avant l'existence de cette étape. La seule conséquence est l'attente : comptez à nouveau plusieurs minutes.

Deux points à connaître :

  • ne lancez pas deux castor wt:up en même temps sur le même worktree — ce n'est pas un mode supporté. Deux wt:up sur des worktrees différents ne se gênent pas ;
  • une interruption brutale pendant la copie (un kill -9, une coupure) peut laisser un répertoire vendor.seed-tmp.* à la racine du worktree. Il est gitignoré et sans effet sur la stack, mais il occupe de l'espace disque — supprimez-le à la main quand vous le croisez.

Le détail des messages : L'amorce de vendor/ sur un worktree neuf.

wt:up échoue sur le démarrage de la stack

La cible sort en 1 en affichant La stack du worktree … n'est pas montée. et la commande à jouer : cd <chemin du worktree> && castor wt:shell. Le conteneur php reste debout — le supervisor bascule en mode maintenance au lieu de sortir — et la réparation se fait depuis l'intérieur. Parcours complet : Réparer un worktree dont la stack ne démarre plus.

wt:up s'arrête sur le proxy hôte

wt:up appelle castor proxy:up, qui contrôle désormais l'adresse réellement obtenue par le conteneur caddy-proxy sur le réseau kirexo-proxy. Deux formes d'échec, un seul fait explicatif : un autre conteneur occupe 172.31.1.2, l'adresse à laquelle la règle de cloisonnement DOCKER-USER s'adosse.

Le diagnostic nomme l'occupant. C'est en général une stack mutualisée ou un worktree démarré pendant que le proxy était arrêté — l'ordre de démarrage suffit à produire le cas sur un réseau créé avant que sa plage dynamique ne soit bornée.

Le remède est une cible dédiée, qui recrée le réseau — son plan d'adressage ne se modifie pas en place :

castor proxy:migrate      # descend les stacks attachées, recrée le réseau borné, relance le proxy

Elle ne remonte pas les stacks qu'elle a descendues : rejouez castor wt:up <ticket> pour chaque worktree, y compris ceux qui étaient déjà arrêtés. Détail des trois cas qu'elle traite et de ce qu'elle refuse de toucher : castor proxy:migrate.

J'ai supprimé le répertoire du worktree à la main

wt:up se relève seul. Les worktrees créés par la cible sont verrouillés (git worktree add --lock) pour qu'un git worktree prune — appelé aussi par git gc — ne supprime pas leurs métadonnées depuis le conteneur, où le gitdir des autres worktrees pointe des chemins hôte inexistants. Un répertoire effacé à la main laisse donc des métadonnées verrouillées, et un git worktree add échouerait ensuite sur missing but locked worktree.

Relancez simplement :

castor wt:up 185

Le rapport affiche une ligne ~ worktree git mentionnant les métadonnées orphelines purgées, puis le worktree est recréé.

Ce raccourci peut couper la sortie réseau de tout le poste

wt:destroy re-parente les conteneurs mutualisés montés depuis le worktree avant de retirer le répertoire ; un rm -rf ne le fait pas. Les cibles Castor ne créent plus ces deux projets que depuis le dépôt principal, mais un conteneur antérieur à cet ancrage — ou créé par un docker compose up lancé à la main — porte toujours l'ancien parentage. Si ce worktree était celui depuis lequel kirexo-shared ou kirexo-proxy avaient été démarrés, leurs conteneurs pointent désormais un chemin disparu : egress-proxy repart en boucle sur FATAL: Unable to open configuration file au premier redémarrage — plus aucune sortie réseau, dans aucun worktree — et le Caddy hôte tombe au reboot suivant. Le contrôle et la réparation sont dans Le proxy redémarre en boucle sur Unable to open configuration file. Préférez castor wt:destroy <ticket>, qui traite le cas.

castor firewall:status affiche n'importe quoi dans mon worktree

Cas nominal, et sans gravité : vous l'avez lancée depuis le conteneur du worktree. Le dépôt principal — d'où l'allowlist du proxy est rendue — n'y est pas monté, donc la cible lit /app/infra/firewall, c'est-à-dire les fichiers du worktree. Elle le signale (⚠️ Worktree : cette whitelist n'est PAS celle que le proxy applique) et affiche le dossier lu. Il n'y a rien à corriger : ce sont les sondes qui mesurent la sortie réelle, et la liste de référence se lit depuis un terminal hôte. Cf. Une seule whitelist, celle du dépôt principal.

Cas à corriger : un répertoire root-owned à la place du fichier. infra/firewall/whitelist.local.txt est gitignoré : il est absent de tout worktree neuf, et c'est wt:up qui le recrée depuis le .dist, avant de démarrer les conteneurs. Si un docker compose up a été lancé à la main avant le premier wt:up, Docker a créé un répertoire root-owned à la place du fichier attendu par le bind :ro. castor confinement:check rend alors C4 ✗ KO « substrat manquant » et la session Claude refuse de démarrer en bypassPermissions.

wt:up signale le problème (! whitelist locale) sans jamais le corriger : aucune cible Castor n'exécute de commande privilégiée. Le remède est manuel :

sudo rmdir <chemin du worktree>/infra/firewall/whitelist.local.txt
castor wt:up <ticket>   # recrée le fichier depuis le .dist, avant le démarrage

wt:up refuse le nom que je lui donne

Huit noms sont refusés, et le refus tombe avant toute création — jamais de worktree à moitié créé :

Nom refusé Raison
demo Collision d'adresse de site : il produirait app.demo.localhost, l'adresse que le repli déclare déjà en dur pour le site de démonstration. Caddy refuse alors de recharger sa configuration (duplicate site address), et le refus fait tomber tous les worktrees d'un coup, pas seulement le fautif.
app, mailpit Ambiguïté de lecture, pas collision : ce sont des préfixes de service. Un worktree mailpit produirait app.mailpit.localhost, docs.mailpit.localhost et mailpit.mailpit.localhost — trois adresses uniques, que Caddy recharge sans broncher depuis que le bloc mailpit.localhost a quitté le repli. Mais mailpit.mailpit.localhost se lit aussi bien « la boîte du worktree mailpit » que « le worktree mailpit.mailpit », et docs.app.localhost aussi bien « la doc du worktree app » que « le worktree docs.app ». Le refus ferme l'ambiguïté au nom.
localhost, www Ambiguïté de routage.
shared, proxy Collision de nom de projet Compose : le projet d'un worktree vaut kirexo-<nom>, donc wt:up shared viserait kirexo-shared, la stack mutualisée.
main Il désigne le dépôt principal, servi par sa propre conf de site (01-main.caddy).

Le nom doit par ailleurs être un label DNS strict : minuscules, chiffres et tirets, 32 caractères au maximum.

https://<worktree>.localhost ne répond plus, ou avertit

Cette forme d'URL — sans préfixe de service — n'est plus servie : l'application d'un worktree vit sur https://app.<worktree>.localhost. Un signet ou un /etc/hosts datant d'avant le renommage vise donc un nom que plus aucun bloc de site ne déclare ; il tombe dans le repli *.localhost, avec le certificat wildcard qui en découle.

L'avertissement de certificat est le symptôme commun. Ce que vous obtenez derrière dépend de qui est le worktree par défaut du proxy : le joker *.localhost du repli route vers le conteneur de ce worktree-là (infra/proxy/fallback.caddy.tpl), qui n'est pas forcément le vôtre.

Deux commandes le disent, à jouer côté hôte :

castor proxy:status   # section « Sites chargés » : la ligne `worktree par défaut : …`
castor wt:list        # le `*` de la colonne `ticket`

Les deux cas :

  • votre worktree est le worktree par défaut — le cas d'un poste qui n'a qu'un seul worktree, puisque le premier castor wt:up prend la place et que les suivants ne la volent pas (Les domaines de site publics et le worktree par défaut). Le repli renvoie alors vers votre conteneur, et son KIREXO_RESERVED_DOMAINS liste bien <worktree>.localhost à côté de app.<worktree>.localhost — wt:up l'y écrit à la génération comme à la réconciliation (infra/worktree/env.lib.sh). L'application répond : il ne reste que l'avertissement de certificat ;
  • un autre worktree est le worktree par défaut : le repli envoie la requête à son conteneur, dont la liste réservée ne porte pas votre nom. La comparaison étant une égalité exacte, l'application le prend pour un domaine de site public, n'en trouve aucun, et rend 404 sur toutes ses routes, /login compris, pendant que le proxy répond parfaitement.

Autrement dit, l'ancien nom n'est resté dans la liste réservée que pour les signets, et il n'achète ce répit que sur le worktree propriétaire du nom. Mécanisme et formulation qui fait autorité : KIREXO_RESERVED_DOMAINS.

Dans les deux cas, le remède est le même : mettre à jour le signet sur https://app.<worktree>.localhost. Si les nouvelles URLs avertissent aussi, ou rendent 502, c'est que le poste n'a pas terminé sa migration : Migrer un poste existant vers les URLs app..

wt:destroy sort en erreur sur le re-parentage d'un singleton

La destruction s'arrête sur un message de cette forme, et la commande sort en 1 :

kirexo-shared : egress-proxy référence(nt) encore le worktree, ou ne tourne(nt) pas.
Au prochain redémarrage, Docker recréera des dossiers root-owned à sa place.

Docker a répondu :
  …

À jouer depuis /home/…/kirexo :
    docker compose -p kirexo-shared -f compose.shared.yaml up -d --force-recreate --wait egress-proxy

Ne l'ignorez pas : le worktree n'est pas encore supprimé, et le service concerné pointe toujours sur un répertoire qui va disparaître. Jouez la ligne donnée depuis le dépôt principal — elle est complète, projet et fichier Compose compris —, puis relancez castor wt:destroy <ticket> : les étapes déjà faites sont des no-op.

Deux causes couvrent l'essentiel des cas :

  • le service n'existe pas dans le fichier Compose du dépôt principal (no such service dans la réponse de Docker) : le dépôt principal est souvent sur main, qui peut ignorer un service ajouté sur la branche du worktree. Mettez main à jour, ou recréez le service depuis un autre worktree qui déclare le fichier attendu ;
  • le service repart en boucle : le message le dit (« ou ne tourne(nt) pas »). Le diagnostic est dans Diagnostiquer un blocage réseau sortant.

Ne « repartez » jamais d'un down -v sur kirexo-proxy

Son volume caddy_proxy_data porte la CA racine locale, émise pour dix ans : la détruire obligerait à rejouer castor cert:trust sur tous les postes, et ferait avertir les navigateurs sur toutes les URLs *.localhost entre-temps. Le remède est toujours une recréation de service (up -d --force-recreate).

Le worktree est enregistré sur un autre chemin

wt:up s'arrête en affichant le chemin enregistré et le chemin attendu, sans jamais déplacer quoi que ce soit — git worktree move déplacerait le travail de quelqu'un sans le lui demander. Deux issues : déplacer vous-même (git worktree move), ou aligner KIREXO_WORKTREES_DIR sur le chemin existant.

Pour aller plus loin