Un git worktree es un directorio de trabajo adicional vinculado a un repositorio existente. Posee su propia rama desprotegida, su propio índice y sus propios archivos no rastreados, pero comparte el almacén de objetos, las referencias y la configuración con el repositorio principal. Para agentes de programación paralelos, es la unidad de aislamiento perfecta: cada agente dispone de un directorio donde ningún otro proceso escribe, sus commits se dirigen a una rama exclusiva y crear el entorno es una simple desprotección (checkout) en lugar de un pesado clonado o arranque de contenedor. Este artículo analiza los comandos esenciales, por qué los worktrees superan al directorio compartido, los fallos típicos y cómo Ivy Tendril crea un worktree por plan y lo elimina automáticamente tras el merge.
Qué es un worktree
Cada repositorio Git cuenta por defecto con un directorio de trabajo. Con git worktree add es posible añadir más. Cada uno es un checkout funcional donde se puede hacer cd, editar archivos, compilar y confirmar cambios.
# Crear un worktree en un directorio superior con una nueva rama
git worktree add ../feature-x -b feature-x
# Listar todos los worktrees del repositorio
git worktree list
# /Users/dev/app a1b2c3d [main]
# /Users/dev/feature-x a1b2c3d [feature-x]
La nueva carpeta contiene un archivo .git (no un directorio). Este archivo apunta a .git/worktrees/feature-x en el repositorio principal, que mantiene el índice y el puntero HEAD específicos. Los objetos, las referencias, los hooks de Git y la configuración se leen directamente del repositorio raíz. Un commit realizado en ../feature-x es inmediatamente visible desde el checkout principal con git log feature-x, sin necesidad de push o fetch.
De esta arquitectura se desprenden dos restricciones claras: una rama solo puede estar activa en un único worktree a la vez, y el directorio del worktree debe ubicarse fuera del directorio raíz para no interpretarse como archivos sin seguimiento.
Por qué los worktrees superan a un directorio compartido
Un agente de programación lee y edita código, lanza comandos y realiza commits. Si dos agentes actúan en el mismo directorio, generan un diff conjunto caótico y las pruebas pierden su capacidad de evaluar cambios aislados. Las alternativas son un clon completo por agente, un contenedor por agente o un worktree por agente.
| Enfoque | Árbol y rama independientes | Almacén de objetos compartido | Coste de arranque | Aislamiento de ejecución |
|---|---|---|---|---|
| Directorio compartido | No | Sí | Ninguno | Ninguno |
| Clon por agente | Sí | No (copia íntegra) | Clonado completo + instalación | Ninguno |
| Contenedor por agente | Sí | No (salvo montado) | Descarga de imagen + inicio | Sí |
| Worktree por agente | Sí | Sí | Checkout instantáneo | Ninguno |
El worktree entrega al agente lo indispensable para la corrección funcional (árbol y rama privados) sin la sobrecarga innecesaria de un entorno virtualizado completo. Al compartir el almacén de objetos, un proyecto con años de historial solo requiere el checkout del estado actual. Las cachés de gestores como pnpm, Cargo o NuGet se conservan de forma natural en el directorio de usuario.
Los contenedores siguen siendo idóneos cuando los agentes deben instalar paquetes del sistema operativo o enlazar puertos de red. Ambos métodos son compatibles: un worktree puede montarse dentro de un contenedor. Para tareas cotidianas de edición, pruebas y confirmación, un worktree es más que suficiente.
Consulte patrones de orquestación de agentes para profundizar en el diseño integral de arquitecturas de aislamiento.
Problemas comunes y cómo solventarlos
Los worktrees eliminan colisiones de carpetas, pero no evitan por sí solos tres desafíos concretos.
1. Dos agentes modificando los mismos archivos en ramas distintas
Los worktrees aíslan rutas, no la intención semántica. Si dos planes modifican auth/session.ts, ambas ramas se confirmarán con éxito por separado, pero la segunda provocará un conflicto al fusionar. Esto debe atajarse en la fase de planificación: analice qué módulos se tocan y ordene los planes secuencialmente o fragméntelos para que cada plan sea dueño de un módulo.
2. Árboles con cambios residuales (Dirty Trees)
Si un agente se detiene inesperadamente o una prueba genera artefactos, el worktree queda con cambios sin confirmar. git worktree remove rechaza por seguridad borrar un árbol modificado. La política correcta de un orquestador consiste en confirmar los cambios residuales en la rama correspondiente para no perder información antes de su desmantelamiento.
# Inspeccionar estado
git -C ../feature-x status --short
# Borrar worktree limpio
git worktree remove ../feature-x
# Forzar eliminación tras verificar
git worktree remove --force ../feature-x
3. Worktrees abandonados
Los worktrees creados de forma manual tienden a acumularse, bloqueando ramas y consumiendo espacio. Si se borra una carpeta con rm -rf en lugar de git worktree remove, Git conserva registros obsoletos en .git/worktrees/.
# Simular limpieza
git worktree prune --dry-run --verbose
# Limpiar referencias obsoletas
git worktree prune
La regla de oro es uniforme: la entidad que inicializa un worktree debe ser responsable de desmantelarlo en un punto específico del ciclo de vida.
Cómo implementa Ivy Tendril los worktrees
Ivy Tendril es una aplicación de escritorio local (macOS, Windows, Linux) que guía a los agentes desde la planificación hasta la pull request revisada. Los worktrees constituyen su núcleo de ejecución. Consulte el resumen de producto y la guía del ciclo de vida.
- Un worktree por plan: Cuando un plan se aprueba, Tendril genera automáticamente un worktree y su rama. Múltiples planes coexisten sin ensuciar la rama principal.
- Verificación en el worktree: Pruebas y diffs se calculan estrictamente dentro del árbol del plan. La vista Review expone el diff junto a los informes de pruebas.
- Limpieza automática: Al completarse la fusión del PR en GitHub, Tendril destruye el worktree de forma transparente.
- Compatibilidad universal: El agente ejecutado puede ser Claude Code, Codex CLI, Copilot CLI, Gemini CLI o cualquier CLI similar.
- Operación local: Worktrees, código, planes y registros se retienen en su ordenador. Vea desarrollo local de IA.
Empiece hoy con Ivy Tendril
Incorpore paralelismo riguroso a su flujo de ingeniería con agentes de software:
- Inspeccione el código: Acceda a Ivy Tendril en GitHub (código abierto).
- Consulte la documentación: Revise las guías en tendril.ivy.app.
- Sesión técnica: Escriba a renco@ivy.app para reservar una sesión de arquitectura de 30 minutos.