Worktrees

Un worktree git est une deuxième copie de travail du dépôt, sur une autre branche, dans un autre dossier. Joppa en fait un environnement : la même application, avec ses propres domaines, ses propres ports, son .env et, si vous voulez, sa propre base de données. Vous gardez main en ligne pendant qu’une branche (ou un agent comme Claude Code) travaille à côté, sans conflit de ports ni de données.

L’onglet Worktrees (W) d’un projet liste ses worktrees. Il apparaît pour les projets dont le dossier est un dépôt git.

Ce que reçoit un worktree

Ses domaines

Le nom de la branche devient un label du domaine : feature/Login UI donne feature-login-ui (un worktree détaché prend le nom de son dossier).

Domaine du projet	Domaine du worktree
monprojet.test	feature-login-ui.monprojet.test
app.monprojet.test	app.feature-login-ui.monprojet.test

Si ce nom est déjà pris (une branche api alors que le projet a api.monprojet.test), Joppa ajoute un numéro : api-2. Les certificats couvrent ces domaines sans rien à faire. Seuls les domaines qui pointent vers un serveur de dev du projet sont repris.

Ses ports

Chaque serveur de dev reçoit un port à lui : celui du projet + 100, + 200… (5173 → 5273), sinon un port libre entre 41000 et 49999. Jamais le port d’un autre projet, ni un port déjà occupé.

Joppa le lui transmet de la façon que le serveur comprend :

1. la variable que Joppa renseigne déjà (${PORT:-3000} dans le script, SERVER_PORT pour php artisan serve, REVERB_SERVER_PORT pour Reverb) ;
2. la variable que le serveur lit (API_PORT dans son code, PORT dans son .env) ;
3. le port écrit dans le script (vite --port 5173), réécrit ;
4. --port pour Vite, Astro, Next.js, Nuxt, Angular, Wrangler, Storybook, Vue CLI, Docusaurus, Gatsby, VitePress et Expo (avec PORT en plus) ; PORT pour Create React App.

Un serveur dont le port n’est fixé que dans le code, sans variable, ne peut pas être déplacé : Joppa le laisse décoché de « Tout démarrer » et le signale.

Un serveur qui lit l’adresse d’un autre dans une variable avec une valeur par défaut (process.env.API_URL ?? "http://localhost:47400") reçoit la nouvelle adresse : le front du worktree parle à l’API du worktree, pas à celle du projet.

Les services Docker Compose restent ceux du projet : le worktree s’en sert, sans lancer une deuxième copie (leurs ports sont fixes).

Son .env

Git ne copie pas les fichiers qu’il ignore. Joppa copie dans le worktree ceux qui lui manquent : .env, .env.local, .env.development, .env.development.local, .dev.vars (Wrangler) et le .php.ini, ainsi que les épinglages de version (.php-version, .node-version, .nvmrc, .tool-versions) quand ils n’ont pas été commités, à la racine et dans le dossier de chaque serveur de dev. Il y remplace les adresses : localhost:5173 → localhost:5273, VITE_PORT=5173 → 5273, https://app.monprojet.test → https://app.feature-login-ui.monprojet.test.

Sa base de données

Pour chaque base que le projet utilise dans un service Joppa :

Choix	Ce que fait Joppa
Une copie de celle du projet (par défaut)	Crée monprojet_feature_login_ui à partir de la base du projet : TEMPLATE pour PostgreSQL (instantané), sinon une copie par dump (PostgreSQL utilisé par un serveur en cours, MySQL, MariaDB)
Une base vide	Crée une base vide ; pour Laravel, php artisan migrate si les dépendances sont installées pendant la préparation
Celle du projet	Le worktree utilise la même base que le projet

Le .env du worktree reçoit le nom de sa base. Redis, Valkey, Mailpit et les moteurs de recherche sont partagés avec le projet.

Une base SQLite (Laravel avec DB_CONNECTION=sqlite, ou un DATABASE_URL en file:, celui de Prisma compris) suit le même choix : le fichier est copié, créé vide (Laravel lance alors ses migrations si les dépendances sont installées), ou le .env du worktree pointe vers celui du projet. Git ignore ces fichiers : sans cela, le worktree n’aurait pas de base.

Ses processus

Les processus du worktree sont ceux du projet, avec ses ports, workers Laravel compris : Reverb reçoit son port par REVERB_SERVER_PORT, et le REVERB_PORT du .env copié suit. Quand la file Laravel passe par Redis (Horizon, ou QUEUE_CONNECTION=redis), les processus php artisan du worktree reçoivent leur propre REDIS_PREFIX et HORIZON_PREFIX (monprojet_database_feature_login_ui_) : ses workers ne prennent jamais les jobs du projet. Xdebug suit les réglages du projet. Ils sont gardés dans la configuration de Joppa, pas dans joppa.toml. Quand vous enregistrez les processus du projet, ceux de ses worktrees suivent (un nouveau processus reçoit son port) ; Mettre à jour depuis monprojet le fait à la demande.

Ses serveurs de dev se mettent en veille après 15 minutes sans requête et se réveillent à la suivante : plusieurs dizaines de worktrees peuvent rester ouverts sans garder chacun leurs serveurs en mémoire.

Préparer un worktree

Dans l’onglet Worktrees, Préparer sur un worktree « pas préparé ». Choisissez sa base, puis cochez au besoin :

• Installer ses dépendances : bun install (ou le gestionnaire du projet) s’il n’a pas de node_modules, composer install s’il n’a pas de vendor ;
• Démarrer ses processus une fois prêt.

Le journal de la préparation s’affiche ; Ouvrir mène à l’environnement.

Créer un worktree

Nouveau worktree fait le git worktree add puis prépare l’environnement :

• Nouvelle branche, à partir du commit actuel ou d’une autre branche, ou Branche existante ;
• le dossier est créé à côté du dépôt : monprojet-worktrees/<branche>.

Les worktrees créés ailleurs

Avec Préparer automatiquement les nouveaux worktrees (activé par défaut), Joppa regarde les worktrees du projet toutes les 3 secondes et prépare ceux que git, Claude Code, Conductor ou un autre agent vient de créer : domaines, ports, .env et base, avec le choix de Base d’un nouveau worktree. Rien n’est installé ni démarré : l’outil qui a créé le worktree s’en charge en général. Une notification annonce l’environnement prêt, avec Ouvrir. Ces deux réglages se partagent avec l’équipe dans la section [worktrees] de joppa.toml.

Seuls les worktrees créés après la mise en route sont préparés tout seuls : ceux qui existaient déjà attendent Préparer.

L’environnement d’un worktree

Il apparaît dans la barre latérale sous son projet, marqué ⎇ et nommé d’après sa branche. Sa page est celle d’un projet (domaines, processus, .env, runtime, analytics), avec en tête le rappel de la branche et :

• Ouvrir monprojet ;
• Mettre à jour depuis monprojet ;
• Supprimer… : ses domaines disparaissent et ses processus s’arrêtent. Cochez au besoin Supprimer ses bases (celles créées pour lui) et Supprimer le dossier du worktree (git worktree remove, refusé s’il a des modifications non commitées, sauf avec Même avec des modifications non commitées).

Si vous gardez le dossier, Joppa ne le prépare plus de lui-même (« laissé de côté ») ; Préparer le reprend.