OpenCode Worktree: separa tareas de programación con Git

Un Git worktree es otro directorio de trabajo conectado al mismo repositorio. El checkout principal puede quedarse en main, mientras una carpeta hermana usa work/auth. Cada carpeta tiene archivos y una rama diferentes. Git comparte los objetos y el historial, así que no hace falta clonar todo el repositorio para cada tarea.

Este flujo no requiere un modo especial de OpenCode. Inicia la CLI desde la carpeta nueva y esa carpeta será el contexto del proyecto. La configuración global puede seguir aplicándose, pero los archivos locales sin seguimiento y la preparación del entorno no se copian automáticamente.

Primero revisa el checkout actual. Empezar desde un estado limpio ayuda a identificar qué cambio pertenece a la tarea principal y cuál a la rama nueva. Desde la raíz del repositorio, crea una rama y su worktree en una carpeta hermana, fuera del directorio original.

El ejemplo crea work/auth desde el commit actual y lo coloca en ../app-auth. Si la rama ya existe, comprueba que no esté activa en otro worktree antes de reutilizarla. Git normalmente impide tener la misma rama seleccionada en dos worktrees enlazados a la vez.

Ejecuta estos comandos desde la raíz del repositorio. La rama nueva parte del commit actual.

git status --short --branch
git worktree add -b work/auth ../app-auth
cd ../app-auth
opencode
git worktree list
git -C ../app-auth status --short --branch

Después de cd ../app-auth, ejecuta opencode en esa terminal. El directorio actual marca el contexto: usa una terminal o sesión independiente por worktree y comprueba la raíz del proyecto antes de permitir cambios. Una primera petición de solo lectura puede pedir un resumen de la rama y los archivos que se van a revisar.

Asigna una tarea concreta a cada sesión e indica el nombre de la rama. Por ejemplo, una carpeta puede actualizar las pruebas de autenticación y otra la documentación. Evita que dos sesiones editen el mismo archivo o escriban en una salida generada común. Separar carpetas reduce conflictos, pero no coordina agentes automáticamente.

El worktree separa los archivos controlados por Git y el índice, pero no es un contenedor ni una frontera de seguridad. Una base de datos local, un servidor de pruebas, una caché, Docker o una cuenta externa pueden seguir compartidos. Si la tarea necesita esos servicios, usa una base, esquema, puerto o entorno desechable diferente.

Git recupera los archivos rastreados del commit elegido. .env, certificados, cachés y resultados de compilación ignorados o sin seguimiento no tienen por qué aparecer en el worktree nuevo. Recrea solo el entorno necesario, carga los secretos mediante el mecanismo aprobado y revisa git status --short --branch antes y después del trabajo.

Revisa la rama del worktree como un cambio independiente. Inspecciona git diff, ejecuta las comprobaciones del proyecto y confirma que solo incluye los archivos previstos. Cuando las pruebas pasen, fusiona o aplica rebase según el proceso del equipo. Los cambios no aparecen en otro checkout hasta compartir commits.

Antes de borrar, busca cambios sin confirmar y decide si guardarlos, confirmarlos o conservarlos. git worktree remove ../app-auth elimina un checkout limpio; Git bloquea la operación si detecta cambios, salvo que fuerces la eliminación. No uses fuerza como limpieza habitual. git worktree prune quita registros obsoletos, no borra worktrees activos.

Elige un worktree cuando las tareas necesiten ramas distintas, instantáneas independientes o una frontera de revisión que pueda durar días. Para investigar sin modificar archivos, o para leer cambios sin confirmar, otra sesión en el mismo checkout suele ser más sencilla. Si las tareas son secuenciales, basta con cambiar de rama.

El worktree añade pasos de nombres, dependencias, aislamiento de servicios, pruebas, fusión y limpieza. Si dos agentes modifican los mismos archivos, separarlos puede complicar la integración. Divide primero el trabajo en cambios que no se solapen o ejecuta esas ediciones en orden.

Si git worktree add indica que la rama ya está activa, consulta git worktree list y crea otra rama o vuelve al checkout existente. Si OpenCode muestra archivos inesperados, revisa la ruta de la terminal y la raíz del proyecto. Los archivos ignorados y sin seguimiento no forman parte del checkout.

Si las pruebas de dos sesiones interfieren, busca recursos externos a Git: bases de datos, puertos, carpetas temporales, generadores y cachés compartidas. Si no puedes eliminar un worktree, ejecuta git status dentro y conserva los cambios útiles antes de limpiar. Mantén la carpeta principal disponible para integrar las ramas.