¿Qué es un git worktree?

En breve

Un git worktree es una carpeta de trabajo adicional asociada al mismo repositorio git. Cada carpeta tiene una rama distinta en checkout, así que puedes trabajar en dos cosas a la vez sin volver a clonar el repo y evitar que agentes de código en paralelo se estorben.

Cómo funciona

Normalmente la carpeta de un repo tiene una rama en checkout, y cambiar de rama implica hacer commit o stash antes. Con un worktree, tu carpeta principal se queda como está y se añade a su lado una carpeta nueva con otra rama. Las carpetas comparten el historial de commits y la base de datos de objetos, pero cada una tiene su propio HEAD, su índice y sus archivos de trabajo.

Los comandos básicos

Un puñado de comandos cubre el uso diario.

git worktree add ../feature-a -b feature-a: crea una rama nueva y su carpeta.
git worktree list: muestra los worktrees abiertos.
git worktree remove ../feature-a: elimina la carpeta.
git worktree prune: limpia los registros de carpetas borradas a mano.

Por qué importa para los agentes de código

Dos agentes en la misma carpeta pueden sobrescribirse los archivos, y la ejecución de pruebas de uno puede tropezar con el cambio a medias del otro. Dar a cada agente su propio worktree lo evita: cada uno trabaja en su rama y combinas los resultados con un pull request o un merge. Las ramas que tocan el mismo archivo aún pueden entrar en conflicto al fusionarlas.

Cosas a tener en cuenta

Los worktrees son ligeros, pero algunos detalles pillan desprevenida a la gente.

La misma rama no puede estar en checkout en dos worktrees a la vez.
Los archivos sin seguimiento, como node_modules, .env y la salida de compilación, no se copian; puede que tengas que volver a instalar las dependencias.
Si cada worktree ejecuta su propio servidor de desarrollo, vigila los choques de puertos.
Elimina los worktrees que ya no uses o las carpetas olvidadas se acumulan en el disco.

Worktrees en AgentVera

AgentVera usa los worktrees como base para ejecutar agentes en paralelo.

Desde el panel de worktrees de “Git”, abre una rama y una carpeta por funcionalidad y arranca un agente directamente en esa carpeta.
En el turno de noche (“night shift”), cada tarea se ejecuta en su propio worktree en una rama night/<fecha>-<slug>; el agente hace commit pero nunca push (Pro y Team).
Los entornos de vista previa ejecutan el servidor de desarrollo del proyecto y de cada worktree en su propia dirección, con el nombre de la rama.
La coordinación de agentes avisa cuando agentes en worktrees distintos cambian el mismo archivo, ya que la fusión puede tener conflictos.

Preguntas frecuentes

¿Qué diferencia hay entre un worktree y una rama?

Una rama es una línea de commits con nombre; un worktree es una carpeta donde hay una rama en checkout. Solo con ramas cambias dentro de una carpeta; con worktrees mantienes varias ramas abiertas a la vez en carpetas separadas.

¿En qué se diferencia un worktree de clonar el repo dos veces?

Los worktrees comparten un único repositorio: commits, ramas y configuración son comunes y ocupan menos disco. Un commit hecho en un worktree se ve al instante desde los demás, mientras que los clones separados necesitan push y fetch.

¿Cómo elimino un worktree?

Ejecuta git worktree remove <carpeta>. Si borraste la carpeta a mano, git worktree prune limpia el registro. La rama se conserva; bórrala aparte con git branch -d si hace falta.

¿Los worktrees comparten node_modules?

No. Los archivos sin seguimiento son independientes en cada carpeta, así que instalas las dependencias en cada worktree.