Cap 3: Git Worktrees en Orca

Qué son los Git Worktrees

Un git worktree es una copia de trabajo adicional de tu repositorio que comparte el mismo .git pero opera en un directorio separado con su propio branch. Esto significa que puedes tener múltiples branches checked out simultáneamente sin hacer git stash o git switch.

# Sin worktrees: un solo directorio, un solo branch
~/proyecto/  →  branch: main

# Con worktrees: múltiples directorios, múltiples branches
~/proyecto/           →  branch: main
~/proyecto-wt/auth/   →  branch: feat/auth
~/proyecto-wt/api/    →  branch: fix/api-error
~/proyecto-wt/ui/     →  branch: refactor/ui

Por qué Orca usa Worktrees

El problema fundamental del desarrollo multi-agente es el conflicto de archivos. Si dos agentes editan el mismo archivo en el mismo directorio, se producen colisiones. Los worktrees resuelven esto de forma nativa en Git:

flowchart LR
    subgraph "Sin Worktrees"
        A1[Agente 1] -->|edita| F1[src/app.ts]
        A2[Agente 2] -->|edita| F1
        F1 -->|CONFLICTO| X[Error]
    end

flowchart LR
    subgraph "Con Worktrees"
        B1[Agente 1] -->|edita| F2[wt-auth/src/app.ts]
        B2[Agente 2] -->|edita| F3[wt-api/src/app.ts]
        F2 -->|merge| M[main]
        F3 -->|merge| M
    end

Cada agente trabaja en su propio worktree con su propio branch. No hay posibilidad de conflicto en tiempo de edición. Los conflictos solo aparecen al hacer merge, donde el desarrollador los resuelve con contexto completo.

Crear Worktrees en Orca

Desde la UI

1. Abre el panel de Worktrees en la sidebar (Ctrl/Cmd + Shift + W)
2. Click en + New Worktree
3. Especifica el nombre del branch (Orca crea el directorio automáticamente)
4. Selecciona el branch base (normalmente main)

Desde la terminal integrada

# Orca provee un wrapper que gestiona las rutas automáticamente
orca worktree create feat/auth

# Equivalente a:
git worktree add ../proyecto-wt/feat-auth -b feat/auth

Desde el CLI

# Crear worktree y asignar agente en un solo comando
orca worktree create feat/auth --agent claude

Gestionar Worktrees

Listar worktrees activos

orca worktree list

Salida:

WORKTREE          BRANCH          AGENT       STATUS
main              main            -           idle
feat-auth         feat/auth       claude      running
fix-api           fix/api-error   codex       running
refactor-ui       refactor/ui     -           idle

Cambiar entre worktrees

En la UI, haz click en cualquier worktree de la sidebar para cambiar el contexto del editor y la terminal.

# Desde CLI
orca worktree switch feat/auth

Eliminar un worktree

# Desde CLI
orca worktree remove feat-auth

# Equivalente a:
git worktree remove ../proyecto-wt/feat-auth

Orca limpia el directorio y el branch tracking automáticamente. Si el worktree tiene cambios sin commit, Orca te advierte antes de eliminar.

Estructura de directorios

Orca organiza los worktrees en una carpeta paralela al proyecto principal:

~/Desarrollos/
  mi-proyecto/              # Repo principal (main)
  mi-proyecto-orca-wt/      # Carpeta de worktrees de Orca
    feat-auth/              # Worktree para feat/auth
    fix-api/                # Worktree para fix/api-error
    refactor-ui/            # Worktree para refactor/ui

Esta convención evita que los worktrees contaminen el directorio del proyecto principal.

Worktrees y el flujo multi-agente

El flujo típico con worktrees en Orca es:

sequenceDiagram
    participant D as Desarrollador
    participant O as Orca
    participant G as Git
    participant A as Agente

    D->>O: "Crea worktree para feature X"
    O->>G: git worktree add
    G-->>O: Worktree creado
    O->>A: Lanzar agente en worktree
    A->>A: Trabaja en branch aislado
    A-->>O: Commits listos
    O-->>D: Notificación: revisar diffs
    D->>O: Aprobar y merge
    O->>G: git merge + worktree remove

Buenas prácticas

1. Un worktree por tarea: no reutilices worktrees para tareas diferentes
2. Nombres descriptivos: usa convenciones como feat/, fix/, refactor/
3. Limpia worktrees: elimina los worktrees después de hacer merge
4. Branch base actualizado: antes de crear un worktree, asegúrate de que main está actualizado

Comandos Git nativos de referencia

Orca abstrae los comandos de Git, pero es útil conocer los equivalentes nativos:

# Crear worktree
git worktree add <ruta> -b <branch>

# Listar worktrees
git worktree list

# Eliminar worktree
git worktree remove <ruta>

# Limpiar worktrees huérfanos
git worktree prune