Git Worktrees explicados: cuándo y por qué usarlos

Un worktree de Git es un directorio de trabajo adicional vinculado al mismo repositorio, con su propia rama activa (checked-out), de modo que puedes tener dos ramas abiertas en dos carpetas a la vez sin necesidad de clonar nada.

La mayoría de los desarrolladores descubre esta necesidad en plena frustración: un stash aplicado a la rama equivocada, un servidor de lenguaje atascado reindexando después de un checkout, o un segundo clon del mismo repositorio que nunca acaba de mantenerse sincronizado. Los worktrees resuelven los tres casos, y vienen incluidos desde Git 2.5, en julio de 2015, así que no hay nada que instalar.

Este artículo cubre qué es realmente un worktree en disco, los tres comandos que gobiernan la funcionalidad, cuándo supera a un stash, cuándo supera a un segundo clon y qué precio tiene.

¿Qué es un worktree de Git en disco?

Un worktree vinculado es un directorio con archivos extraídos (checked out), no una copia de tu repositorio. Su .git de nivel superior es un archivo simple, no un directorio, y apunta a una pequeña carpeta de metadatos dentro de .git/worktrees/ del repositorio principal, una estructura que la documentación de git worktree detalla por completo. Todo lo pesado se queda en un solo lugar: una base de datos de objetos, un historial y un conjunto de refs sirven a todos los worktrees, y solo un puñado de archivos pertenece a un worktree concreto, entre ellos HEAD y el índice.

Ese único hecho explica todo lo demás sobre los worktrees. Crear uno cuesta un checkout, no un clone. Los commits hechos en cualquier worktree son inmediatamente visibles desde todos los demás, porque debajo solo hay un repositorio.

¿Qué flujo de trabajo reemplaza un worktree?

Sin worktrees, una interrupción urgente implica suspender tu estado actual. La secuencia habitual, usando la forma git stash push para que el mensaje quede realmente asociado:

git stash push -m "wip: login form"
git checkout main
git checkout -b hotfix-bug
# fix, commit, push, wait for the merge
git checkout feature-login
git stash pop

Cinco comandos, dos cambios de contexto y una oportunidad de aplicar el stash a la rama equivocada. La versión con worktree es un solo comando:

git worktree add -b hotfix-bug ../hotfix-workspace main

Eso crea una carpeta hermana, crea la rama hotfix-bug a partir de main y la deja activa allí. Tu directorio original queda intacto: la misma rama, los mismos archivos modificados, el mismo editor abierto. Cuando la corrección se fusiona, git worktree remove ../hotfix-workspace elimina la carpeta y la desregistra.

Los tres comandos: add, list, remove

El uso diario de los worktrees se reduce a tres subcomandos. git worktree add <path> <branch> hace checkout de una rama existente en una nueva ruta; añade -b <new-branch> antes de la ruta para crear la rama sobre la marcha. Apunta add a una ruta que aún no existe y Git creará el directorio por ti.

git worktree list muestra todos los worktrees, empezando por el principal, con su ruta, el hash abreviado del commit y la rama activa entre corchetes:

/home/you/project             abc1234 [feature-login]
/home/you/hotfix-workspace    def5678 [hotfix-bug]

git worktree remove <path> elimina un worktree, y las reglas de Git para la eliminación son estrictas: un solo archivo sin seguimiento o un archivo versionado editado detiene el comando a menos que añadas --force, que descarta esos cambios. Git no permite eliminar el worktree principal en absoluto, y uno bloqueado requiere --force dos veces. Si en cambio borras la carpeta de un worktree a mano, git worktree prune limpia los metadatos que quedan atrás.

¿Cuándo supera un worktree a un stash?

Un stash suspende tu trabajo; un worktree deja que siga en marcha. Esa distinción decide cuál te conviene. Un stash está bien para guardar un diff de dos líneas durante diez minutos. Es la herramienta equivocada cuando el trabajo en tu directorio sigue en vuelo: una suite de tests o una compilación larga a medio ejecutar, un servidor de desarrollo vigilando archivos, o un editor cuyo servidor de lenguaje reindexaría todo el proyecto tras un cambio de rama.

Con un worktree, nada de ese estado se altera, porque nunca tocas el directorio original. Abres la nueva carpeta en una segunda ventana del editor, haces allí la tarea que te interrumpió y vuelves para encontrar todo exactamente donde lo dejaste. Ese mismo aislamiento es la razón por la que las herramientas que ejecutan agentes de programación con IA en paralelo han adoptado los worktrees como su modelo de trabajo. Para una visión más personal, el artículo de matklad describe el conjunto fijo de cinco worktrees de un desarrollador, asignados a actividades concurrentes en lugar de a ramas; tómalo como una configuración personal, no como una práctica estándar.

¿Worktree o segundo clon?

Un worktree supera a un segundo clon siempre que ambos directorios deban seguir el mismo repositorio. Como todos los worktrees comparten un único almacén de objetos y un único conjunto de refs, un solo git fetch los actualiza todos, una rama enviada desde uno es visible al instante en los demás, y añadir un worktree no duplica historial en disco. Un segundo clon no te da nada de eso: dos almacenes de objetos que actualizar, dos conjuntos de refs que se desincronizan y el doble de disco.

Un clon sigue siendo la opción correcta en dos casos: cuando el trabajo pertenece a un remoto genuinamente distinto, como un fork con el que interactúas por separado, o cuando quieres un experimento desechable completamente aislado de tu repositorio principal, donde ni siquiera quieres compartir las refs.

¿Qué precio tienen los worktrees?

Git rastrea archivos versionados, no tu entorno. Ese es el principal impuesto de cada nuevo worktree:

• Las dependencias instaladas no vienen incluidas. Un worktree nuevo de un proyecto npm o pip normalmente necesita su propio paso de instalación antes de poder compilar.
• Los archivos locales sin seguimiento se quedan atrás: los archivos .env, la configuración local y las cachés de compilación viven en el directorio original, porque Git no tiene registro de ellos.
• Las carpetas de worktree creadas dentro del repositorio aparecen como desorden sin seguimiento y necesitan una entrada en .gitignore. Los directorios hermanos (../hotfix-workspace) evitan el problema por completo.
• Por defecto, una rama puede estar activa en un solo worktree a la vez. Existen formas de forzarlo (--force en add, --ignore-other-worktrees en switch), pero la respuesta más limpia cuando solo necesitas compilar o probar un commit es un worktree con HEAD desacoplado:

git worktree add -d ../build-check 1a2b3c4

La opción -d deja HEAD desacoplado en la nueva carpeta, así que no se reclama ninguna rama y la restricción nunca se activa. git switch -d <commit> dentro de un worktree existente hace lo mismo.

¿Tienes suficientes cosas en marcha?

La prueba para decidir si adoptarlos es corta. ¿Te llegan interrupciones con regularidad mientras tienes trabajo real sin confirmar en curso? ¿Un cambio de rama dispara una reinstalación de dependencias o una reindexación del servidor de lenguaje que se nota? ¿Ya mantienes un segundo clon del mismo repositorio? Con dos respuestas afirmativas, los worktrees se amortizan la primera semana. Con cero, stash más ramas está perfectamente bien. Empieza con uno: la próxima vez que llegue una corrección urgente a mitad de una funcionalidad, ejecuta git worktree add en lugar de git stash, y elimina la carpeta cuando la corrección se fusione.

Preguntas frecuentes

¿Funcionan los git worktrees con repositorios que usan submódulos?

En parte. El propio manual de Git señala el soporte de submódulos como incompleto en su nota de BUGS, y advierte contra hacer checkout de un superproyecto en más de un lugar a la vez. En la práctica, un worktree vinculado con submódulos dentro no puede reubicarse con git worktree move, y eliminarlo con git worktree remove requiere la opción force. Si tu repositorio depende mucho de los submódulos, un segundo clon es la opción más segura.

¿Se comparten los stashes y las ramas entre git worktrees?

Sí. Todo lo que está bajo refs/ es común a todos los worktrees, así que las ramas, las etiquetas y el stash se ven igual desde donde estés. Tres espacios de nombres son la excepción y permanecen locales a un worktree: refs/bisect, refs/worktree y refs/rewritten. Más allá de esos, solo los punteros propios de un worktree son privados, entre ellos HEAD y su índice. Por tanto, un stash que crees en un worktree puede listarse, y aplicarse, desde cualquier otro worktree del mismo repositorio.

¿Puedo mover un worktree a otra carpeta después de crearlo?

Sí. Pásale a git worktree move el worktree y la ruta donde lo quieres, y Git desplaza la carpeta y reescribe sus metadatos de una sola vez. Dos casos que no gestionará: el worktree principal y cualquier worktree vinculado con submódulos dentro. Un worktree bloqueado necesita la opción force dos veces. Si ya has arrastrado la carpeta a otro sitio por tu cuenta, git worktree repair la vuelve a conectar.

¿Qué ocurre si ejecuto git worktree add solo con una ruta y sin rama?

Git toma la última parte de la ruta como nombre de rama, inicia esa rama en HEAD y la deja activa en la nueva carpeta. Así, git worktree add ../hotfix te deja con una rama llamada hotfix, activa en ../hotfix. Si ese nombre ya está en uso, Git hace checkout de la rama existente en su lugar, siempre que ningún otro worktree la esté ocupando.