Worktrees

Un worktree de git es una segunda copia de trabajo del repositorio, en otra rama, en otra carpeta. Joppa lo convierte en un entorno: la misma aplicación, con sus propios dominios, sus propios puertos, su .env y, si quieres, su propia base de datos. Mantienes main en línea mientras una rama (o un agente como Claude Code) trabaja al lado, sin conflictos de puertos ni de datos.

La pestaña Worktrees (W) de un proyecto lista sus worktrees. Aparece en los proyectos cuya carpeta es un repositorio git.

Lo que recibe un worktree

Sus dominios

El nombre de la rama se convierte en una etiqueta del dominio: feature/Login UI da feature-login-ui (un worktree separado toma el nombre de su carpeta).

Dominio del proyecto	Dominio del worktree
miproyecto.test	feature-login-ui.miproyecto.test
app.miproyecto.test	app.feature-login-ui.miproyecto.test

Si ese nombre ya está ocupado (una rama api cuando el proyecto tiene api.miproyecto.test), Joppa añade un número: api-2. Los certificados cubren estos dominios sin que tengas que hacer nada. Solo se retoman los dominios que apuntan a un servidor de desarrollo del proyecto.

Sus puertos

Cada servidor de desarrollo recibe un puerto propio: el del proyecto + 100, + 200… (5173 → 5273); si no, un puerto libre entre 41000 y 49999. Nunca el puerto de otro proyecto, ni un puerto ya ocupado.

Joppa se lo transmite de la forma que el servidor entiende:

1. la variable que Joppa ya rellena (${PORT:-3000} en el script, SERVER_PORT para php artisan serve, REVERB_SERVER_PORT para Reverb);
2. la variable que lee el servidor (API_PORT en su código, PORT en su .env);
3. el puerto escrito en el script (vite --port 5173), reescrito;
4. --port para Vite, Astro, Next.js, Nuxt, Angular, Wrangler, Storybook, Vue CLI, Docusaurus, Gatsby, VitePress y Expo (con PORT además); PORT para Create React App.

Un servidor cuyo puerto solo está fijado en el código, sin variable, no se puede mover: Joppa lo deja desmarcado de «Iniciar todo» y lo indica.

Un servidor que lee la dirección de otro en una variable con valor por defecto (process.env.API_URL ?? "http://localhost:47400") recibe la nueva dirección: el front del worktree habla con la API del worktree, no con la del proyecto.

Los servicios Docker Compose siguen siendo los del proyecto: el worktree los usa sin iniciar una segunda copia (sus puertos son fijos).

Su .env

Git no copia los archivos que ignora. Joppa copia en el worktree los que le faltan: .env, .env.local, .env.development, .env.development.local, .dev.vars (Wrangler) y el .php.ini, y los fijados de versión (.php-version, .node-version, .nvmrc, .tool-versions) cuando no se han hecho commit, en la raíz y en la carpeta de cada servidor de desarrollo. Sustituye en ellos las direcciones: localhost:5173 → localhost:5273, VITE_PORT=5173 → 5273, https://app.miproyecto.test → https://app.feature-login-ui.miproyecto.test.

Su base de datos

Para cada base de datos que el proyecto usa en un servicio de Joppa:

Opción	Lo que hace Joppa
Una copia de la del proyecto (por defecto)	Crea miproyecto_feature_login_ui a partir de la base del proyecto: TEMPLATE para PostgreSQL (instantáneo); si no, una copia mediante dump (PostgreSQL usado por un servidor en marcha, MySQL, MariaDB)
Una vacía	Crea una base vacía; para Laravel, php artisan migrate si las dependencias se instalan durante la preparación
La del proyecto	El worktree usa la misma base que el proyecto

El .env del worktree recibe el nombre de su base. Redis, Valkey, Mailpit y los motores de búsqueda se comparten con el proyecto.

Una base SQLite (Laravel con DB_CONNECTION=sqlite, o un DATABASE_URL en file:, incluido el de Prisma) sigue la misma elección: el archivo se copia, se crea vacío (Laravel ejecuta entonces sus migraciones si las dependencias están instaladas) o el .env del worktree apunta al del proyecto. Git ignora estos archivos: sin esto, el worktree no tendría base de datos.

Sus procesos

Los procesos del worktree son los del proyecto, con sus puertos, workers de Laravel incluidos: Reverb recibe su puerto mediante REVERB_SERVER_PORT, y el REVERB_PORT del .env copiado le sigue. Cuando la cola de Laravel pasa por Redis (Horizon, o QUEUE_CONNECTION=redis), los procesos php artisan del worktree reciben su propio REDIS_PREFIX y HORIZON_PREFIX (miproyecto_database_feature_login_ui_): sus workers nunca toman los jobs del proyecto. Xdebug sigue los ajustes del proyecto. Se guardan en la configuración de Joppa, no en joppa.toml. Cuando guardas los procesos del proyecto, los de sus worktrees le siguen (un proceso nuevo recibe su puerto); Actualizar desde miproyecto lo hace a petición.

Sus servidores de desarrollo entran en reposo tras 15 minutos sin peticiones y despiertan con la siguiente: decenas de worktrees pueden quedarse abiertos sin que cada uno mantenga sus servidores en memoria.

Preparar un worktree

En la pestaña Worktrees, Preparar en un worktree «sin preparar». Elige su base de datos y, si hace falta, marca:

• Instalar sus dependencias: bun install (o el gestor del proyecto) si no tiene node_modules, composer install si no tiene vendor;
• Iniciar sus procesos una vez listo.

Se muestra el registro de la preparación; Abrir lleva al entorno.

Crear un worktree

Nuevo worktree hace el git worktree add y luego prepara el entorno:

• Rama nueva, a partir del commit actual o de otra rama, o Rama existente;
• la carpeta se crea junto al repositorio: miproyecto-worktrees/<rama>.

Los worktrees creados en otro lugar

Con Preparar automáticamente los nuevos worktrees (activado por defecto), Joppa mira los worktrees del proyecto cada 3 segundos y prepara los que git, Claude Code, Conductor u otro agente acaba de crear: dominios, puertos, .env y base de datos, con la opción de Base de datos de un nuevo worktree. No se instala ni se inicia nada: la herramienta que creó el worktree suele encargarse de ello. Una notificación anuncia que el entorno está listo, con Abrir. Ambos ajustes se comparten con el equipo en la sección [worktrees] de joppa.toml.

Solo se preparan solos los worktrees creados después de activarlo: los que ya existían esperan a Preparar.

El entorno de un worktree

Aparece en la barra lateral bajo su proyecto, marcado con ⎇ y con el nombre de su rama. Su página es la de un proyecto (dominios, procesos, .env, runtime, analytics), con un recordatorio de la rama arriba y:

• Abrir miproyecto;
• Actualizar desde miproyecto;
• Eliminar…: sus dominios desaparecen y sus procesos se detienen. Marca si hace falta Eliminar sus bases de datos (las creadas para él) y Eliminar la carpeta del worktree (git worktree remove, rechazado si tiene cambios sin commit, salvo con Incluso con cambios sin commit).

Si conservas la carpeta, Joppa ya no la prepara por sí solo («ignorado»); Preparar la retoma.