Saltar a contenido

Worktrees

Un worktree es un directorio de trabajo de git aislado, vinculado al mismo repositorio. Cada worktree tiene su propia rama, su propio working tree y — en RaiSE — sus propios archivos de entorno. Son el mecanismo que hace posible el trabajo paralelo real en stories sin cambios de rama ni malabares con stash.

¿Por Qué Worktrees?

Sin worktrees, el trabajo paralelo requiere ciclos constantes de git stash / git checkout, o múltiples clones del repositorio. Ambos son frágiles. git stash pierde cambios silenciosamente con hooks; los clones se desincronizan.

El modelo de worktrees de RaiSE da a cada flujo de trabajo su propio directorio, sus propios archivos .env y su propia vinculación de misión — totalmente aislado del checkout principal y de los demás worktrees.

Modelo de Worktrees de RaiSE

RaiSE gestiona los worktrees como objetos de primera clase registrados en la base de datos consolidada. No son invocaciones crudas de git worktree add — pasan por rai worktree open, que:

  1. Crea el git worktree bajo .worktree/{repo-name}-{slug}/
  2. Propaga los archivos de entorno listados en .worktreeinclude
  3. Registra el worktree en ~/.rai/raise.db con su vinculación de misión
  4. Configura el worktree para los comandos rai (resolución de la ruta del proyecto)

La operación inversa es rai worktree close, que desregistra la entrada y elimina el directorio limpiamente.

Naming de Worktrees

Los worktrees viven en:

.worktree/{repo-name}-{slug}/

Por ejemplo: .worktree/raise-commons-docs-release-31b1/

El slug se obtiene del nombre de la rama o de una etiqueta corta que proporcionas al crearlo.

Propagación de Archivos de Entorno

Los secretos y la configuración local (.env, .env.local, .raise/secrets.yaml) no están trackeados en git pero se necesitan en cada worktree. El archivo .worktreeinclude en la raíz del repo lista qué archivos copiar:

.env
.env.local
.raise/mcp/openai.yaml

rai worktree open lee este archivo y copia cada ruta listada al nuevo worktree. Los cambios a estos archivos en el checkout principal no se sincronizan automáticamente — vuelve a ejecutar rai worktree open --reprovision para refrescarlos.

Vinculación de Misión

Cada worktree se vincula a una misión en el momento de su creación. Las sesiones iniciadas dentro del worktree se vinculan automáticamente a esa misión — sin selección manual.

Este es el patrón recomendado: un worktree por work item, persistente a través de todos los epics y stories vinculados a él. No crees un worktree nuevo por story; crea uno por work item y trabaja las stories secuencialmente (o despliega a múltiples worktrees para tracks de epics en paralelo).

Modelo de Ramas Dentro de un Worktree

Para trabajo a nivel de epic en un worktree, la convención de ramas es:

worktree-{epic-slug}    ← intermediate branch (never pushed to remote)
  └── story/{id}/{name} ← story branches, created and merged here

Las ramas de story se crean desde la rama worktree-{epic-slug} y se mergean de vuelta a ella. Cuando el epic está completo, la rama del epic se mergea a la rama de release vía MR — un único diff limpio por epic.

release/3.1.0
  └── worktree-my-epic   (local only)
       └── story/s1.1/feature-a  (merged back to worktree-my-epic)
       └── story/s1.2/feature-b  (merged back to worktree-my-epic)

Resumen CLI

Comando Qué hace
rai worktree open Crear, registrar y provisionar un nuevo worktree
rai worktree close Desregistrar y eliminar un worktree
rai worktree list Listar worktrees registrados y sus work items vinculados
rai worktree status Mostrar la salud del worktree (rama, vinculación, archivos de entorno)

Próximos Pasos