Git worktree con OpenCode

1. Introducción

Cuando trabajas con un agente como OpenCode, lo normal es pedirle cambios directamente en tu carpeta del proyecto. Esto es cómodo hasta que quieres probar dos ideas a la vez:

• 1️⃣ El agente modifica ficheros a medias y no cambias de rama sin stash o commit chapuceros.
• 2️⃣ Con dos sesiones de opencode en la misma carpeta, pueden sobreescribir los mismos ficheros.
• 3️⃣ Comparar dos variantes te obliga a ir cambiando de rama y perder el estado.

La solución es tener una carpeta por variante, todas apuntando al mismo repositorio. Eso es exactamente lo que vamos a ver en esta guía: el uso de git worktree.

2. Qué es git worktree

Un git worktree es una carpeta adicional vinculada a tu mismo repositorio .git/. Cada carpeta tiene su propia rama activa y su propio estado, pero comparten historial, ramas y objetos. Observa la siguiente estructura:

workspace/
  mi-proyecto/              # worktree principal → rama main
    .git/                   # CARPETA: el repositorio real

  mi-proyecto-hero-a/       # worktree vinculado → rama feat/hero-a
    .git                    # FICHERO (no carpeta)

  mi-proyecto-hero-b/       # worktree vinculado → rama feat/hero-b
    .git                    # FICHERO (no carpeta)

Si miras dentro de ese fichero .git verás que solo es un puntero:

cat ../mi-proyecto-hero-a/.git
gitdir: /home/manz/workspace/mi-proyecto/.git/worktrees/mi-proyecto-hero-a

Teniendo esto claro, hagamos un resumen rápido de las opciones que tenemos utilizando git para hacer pruebas con diferentes variantes de una funcionalidad (y cambiar entre ellas):

Mecanismo	Opción	Problema que tiene...
git branch git checkout	Cambiar de rama en la misma carpeta	❌ Pierdes el trabajo a medias (o usas stash)
git clone	Duplicar todo el repositorio	❌ Duplica .git, hay que sincronizar remotos, ocupa más
git stash	Guardar cambios temporalmente	❌ Solo sirve para apartar, no para trabajar en paralelo
git worktree	Una carpeta por rama, mismo .git	✅ Es la forma adecuada de trabajar en paralelo

3. Conceptos mínimos

Antes de empezar a utilizar git worktree, necesitas conocer tres conceptos:

• 1️⃣ Worktree principal: La carpeta donde clonaste/creaste el repo (~/workspace/mi-proyecto)
• 2️⃣ Worktree vinculado: Cada carpeta extra que creas con git worktree add.
• 3️⃣ Una rama = una carpeta: Git no deja tener la misma rama activa en dos worktrees a la vez. Cada variante necesita su propia rama (feat/hero-a, feat/hero-b).

4. Comandos esenciales

Para utilizar git worktree, con cinco comandos tienes suficiente:

Comando	Para qué sirve
git worktree list	Ver qué carpetas existen y qué rama tiene cada una
git worktree add <ruta> -b <rama>	Crear carpeta nueva con una rama nueva
git worktree add <ruta> <rama-existente>	Crear carpeta para una rama que ya existe
git worktree remove <ruta>	Borrar una carpeta vinculada cuando terminas
git worktree prune	Limpiar restos de carpetas borradas a mano (sin remove)

5. Flujo con OpenCode

La idea es simple: una sesión de opencode por carpeta. Cada agente sólo ve su worktree, así que no se pisan ni mezclan contexto.

~/workspace/
  mi-proyecto/            → main              # estable, no se toca
  mi-proyecto-hero-a/     → feat/hero-a       # variante A
  mi-proyecto-hero-b/     → feat/hero-b       # variante B

Reglas del flujo:

1. El worktree principal se queda en main limpio. No lances agentes ahí.
2. Cada variante tiene su carpeta, su rama y su sesión de opencode.
3. Cuando decides la ganadora, haces merge a main y borras el resto.

6. Ejemplo

Vamos a crear un ejemplo paso a paso con dos variantes del mismo Hero de una landing para compararlas. Partimos de un repo limpio:

cd ~/workspace/mi-proyecto
git status                    # El repo debe estar limpio
git pull                      # Ten el main actualizado

1) Crear los dos worktrees

Creamos las dos variantes que vamos a probar y enganchamos cada una a una rama:

git worktree add ../mi-proyecto-hero-a -b feat/hero-a
git worktree add ../mi-proyecto-hero-b -b feat/hero-b

Ahroa comprueba el resultado:

git worktree list
/home/manz/workspace/mi-proyecto          abc1234 [main]
/home/manz/workspace/mi-proyecto-hero-a   abc1234 [feat/hero-a]
/home/manz/workspace/mi-proyecto-hero-b   abc1234 [feat/hero-b]

Ten en cuenta que cada worktree es una carpeta nueva que viene del repo. Estará limpia y necesitará sus dependencias (hacer un pnpm install en cada una), copiar sus ficheros .env, etc. Si usas un servidor de desarrollo, recuerda configurar que usen un puerto aleatorio para que no se solapen.

2) Lanzar un agente en cada carpeta

Vamos a abrir dos terminales para lanzar un agente en cada una:

cd ~/workspace/mi-proyecto-hero-a
opencode run --agent build "En src/components/Hero.astro, crea una variante minimalista: titular grande, subtítulo corto y un solo botón. No toques nada más."

En otra terminal, haz lo siguiente:

cd ~/workspace/mi-proyecto-hero-b
opencode run --agent build "En src/components/Hero.astro, crea una variante vistosa: titular con gradiente, dos botones y una imagen lateral. No toques nada más."

Cada agente hará los cambios necesarios en su propia rama, e incluso puedes indicarle que haga commit al terminar. Este ejemplo es muy sencillo, pero piensa en variantes donde requieres probar funcionalidades, revisión o cambios incrementales continuos.

Abrir terminales independientes puede resultar incómodo. Tienes opciones alternativas diseñadas para ello como Orca o Herdr, o utilizar multiplexadores de terminal como tmux, byobu o zellij.

7. Elegir variante

Finalmente, cuando ya has probado y testeado ambas, y te has decidido por la ganadora, debes fusionarla a main. Como es una rama, es tan sencillo como hacer lo siguiente:

cd ~/workspace/mi-proyecto     # worktree principal, rama main
git pull
git merge feat/hero-b --no-ff -m "feat: nueva variante de Hero"
git push

Luego, simplemente borra los worktrees que ya no necesitas:

git worktree remove ../mi-proyecto-hero-a
git worktree remove ../mi-proyecto-hero-b
git worktree list
/home/manz/workspace/mi-proyecto   def5678 [main]

Si borraste una carpeta a mano con rm -rf en vez de git worktree remove, git se queda con la referencia colgada. Puedes limpiarla simplemente con un git worktree prune.

8. Consejos

• 1️⃣ Parte siempre de un main limpio: Haz git status y que no hayan cambios.
• 2️⃣ Una rama por variante: si feat/hero-a ya está en una carpeta, git se negará.
• 3️⃣ node_modules o .env no se comparte: dependencias y configuraciones en cada worktree.
• 4️⃣ Revisa .gitignore: Los ficheros ignorados no aparecen en el worktree nuevo.
• 5️⃣ Servidores y BDD: Usa puertos aleatorios para servidores y prefijos diferentes para BDD.
• 6️⃣ Borra al terminar: Haz git worktree list de vez en cuando y remove lo que sobre.
• 7️⃣ Un agente, una carpeta: No abras dos sesiones de opencode apuntando al mismo worktree.