Git worktree qué es y cómo funciona por dentro

En pocas palabras: Un git worktree es una carpeta de trabajo adicional del mismo repositorio, disponible desde Git 2.5 (2015), con su propia rama, HEAD e índice. Comparte commits, ramas, configuración y hooks con el worktree principal, y permite trabajar en main y en una feature branch al mismo tiempo sin clonar ni usar git stash.

git worktree es un comando de Git que crea un directorio de trabajo vinculado al repositorio activo. Cada worktree tiene su propia rama activa, su propio staging y sus propios archivos, pero todos comparten los commits, las referencias (ramas y tags), la configuración y los hooks guardados en la carpeta .git original, según detalla la documentación oficial de git-worktree.

¿Qué problema resuelve git worktree que git stash no resuelve?

git worktree resuelve el problema de necesitar dos ramas activas a la vez sin interrumpir lo que estabas haciendo: agrega una segunda carpeta que lee y escribe en la misma base de datos de git, así que un commit hecho en una aparece de inmediato en la otra. git stash, en cambio, guarda y vacía tu único estado de trabajo, y después tenés que volver a aplicarlo a mano.

Ponele que estás a mitad de feature/payments, con cambios sin terminar, y te piden revisar un bug urgente en main. Tenés tres opciones, y ninguna te cierra del todo: hacer un commit temporal para no perder nada, guardar los cambios con git stash, o clonar el repositorio de nuevo en otra carpeta. Las primeras dos te obligan a cortar lo que estabas haciendo. La tercera duplica todo el historial y te deja con un repositorio aparte que no ve tus ramas locales.

git worktree agrega una cuarta opción. Abrís main en una carpeta nueva, arreglás el bug, hacés commit, y feature/payments sigue intacta donde la dejaste, con sus cambios a medias, según explica la guía detallada de Ramón Chancay sobre git worktree. Las dos carpetas comparten la misma base de objetos. Por eso el commit que hacés en una aparece al toque en la otra.

Opción	Varias ramas a la vez	Duplica el historial	Ve tus ramas locales
Rama + checkout	No	No	—
git stash	No	No	—
Clon nuevo	Sí	Sí	No, solo las subidas con push
Worktree	Sí	No	Sí, todas

¿Qué partes de un repositorio git comparte un worktree y cuáles no?

Un repositorio git tiene tres piezas: la base de objetos (el historial completo), las referencias (ramas y tags) y el estado de trabajo (HEAD, índice y archivos). Un worktree nuevo duplica solo la tercera pieza; las otras dos quedan compartidas entre todas las carpetas del mismo repositorio. Sobre eso hablamos en nuestra comparativa de herramientas CI/CD en 2026.

Pieza	Qué contiene	Dónde vive
Base de objetos	Commits, árboles y contenidos del historial	.git/objects
Referencias	Ramas (refs/heads/main), tags, ramas remotas	.git/refs y .git/packed-refs
Estado de trabajo	Rama activa (HEAD), índice y archivos de la carpeta	.git/HEAD, .git/index y el directorio de trabajo

Un repositorio normal tiene una sola copia de cada pieza. Por eso solo podés estar en un lugar a la vez. Un fetch hecho en un worktree actualiza las ramas remotas para todos, borrar una rama la borra para todos, y el stash es uno solo, visible desde cualquier carpeta.

¿Qué diferencia hay entre el worktree principal y un worktree vinculado?

El worktree principal es la carpeta donde clonaste o iniciaste el repositorio, la que tiene la carpeta .git real; no se puede borrar ni mover con git worktree. Los worktrees vinculados son los que creás con git worktree add, y en vez de carpeta .git tienen un archivo .git de una sola línea.

Ese archivo apunta al registro interno del worktree, algo tipo gitdir: /home/usuario/app/.git/worktrees/app-login. Cuando corrés cualquier comando de git dentro de esa carpeta, git lee ese archivo, sigue la ruta y entiende que forma parte del repositorio principal. Podés verificarlo con git rev-parse --git-dir (te muestra el registro propio) y git rev-parse --git-common-dir (te muestra el repositorio compartido). Lo interesante es que crear un worktree no copia el historial: solo escribe un registro chico y hace el checkout de la rama, y por eso tarda lo que tarda desplegar los archivos, nada más.

Cómo crear, listar y eliminar un git worktree paso a paso

Para crear un worktree usás git worktree add <ruta> <rama>; para verlos todos, git worktree list; para borrarlo, git worktree remove <ruta>. El worktree principal nunca se puede eliminar con este comando. Ya lo cubrimos antes en cuál de las dos plataformas conviene elegir.

• Crear uno con rama nueva: git worktree add -b feature/login ../app-login crea la rama feature/login y la carpeta ../app-login en un solo paso.
• Crear uno sobre una rama existente: git worktree add ../app-hotfix main hace checkout de main en una carpeta nueva, sin tocar la que ya tenés abierta.
• Listar todos los worktrees activos: git worktree list -v muestra la ruta, el commit y la rama de cada uno, incluido el principal.
• Eliminar uno limpio: git worktree remove ../app-login funciona solo si no hay archivos sin trackear ni cambios pendientes; si hay, hace falta --force, según especifica la documentación de git-scm.com.
• Limpiar registros huérfanos: git worktree prune borra la metadata de worktrees cuya carpeta borraste a mano, sin pasar por remove.

¿Por qué una rama no puede estar activa en dos worktrees a la vez?

Una rama solo puede estar activa en un worktree por vez porque cada HEAD apunta a una referencia distinta, y git bloquea que dos carpetas la checkeen al mismo tiempo para evitar que dos índices escriban commits divergentes sobre el mismo puntero. Si intentás hacer git worktree add ../otra main mientras main ya está activa en otra carpeta, git rechaza la operación, salvo que uses --force.

¿Y si igual la fuerzas? Ahí el riesgo lo tomás vos: nada impide que termines con dos carpetas pisándose el estado de la misma rama, algo que casi nunca conviene.

Qué no copia un git worktree al crearse

Un worktree nuevo no trae nada de lo que git no versiona: ni node_modules, ni archivos .env, ni carpetas de build. Solo escribe los archivos que están trackeados en la rama que elegiste.

• node_modules: hay que correr la instalación de dependencias de nuevo en cada worktree, porque no viene con el checkout.
• .env y configuración local: si tu proyecto depende de variables de entorno, las copiás a mano a cada carpeta nueva.
• Carpetas de build: dist, build o target quedan vacías hasta que corras el proceso de compilación en esa carpeta puntual.

Casos de uso reales para git worktree en el día a día

git worktree sirve en cualquier situación donde necesitás dos estados de trabajo vivos sobre el mismo repositorio sin perder el contexto del que ya tenías. No conviene cuando el cambio es corto y no tenés nada a medias, ahí un checkout alcanza. Relacionado: cómo se comparan en seguridad y privacidad.

• Hotfix urgente: arreglás el bug en una carpeta aparte sin tocar la feature a medias que tenías abierta.
• Revisar un pull request: abrís la rama del PR en su propia carpeta, la corrés y la probás sin cambiar de rama en tu entorno de trabajo.
• Tests o builds largos: corrés la suite en un worktree mientras seguís programando en otro, sin bloquear tu terminal principal.
• Agentes de código en paralelo: herramientas como Orca crean un worktree por agente para correr varios a la vez sobre la misma tarea y quedarse con el mejor resultado, según describe la guía de Ramón Chancay.

Errores comunes al usar git worktree

El primer error típico es querer tener la misma rama activa en dos carpetas a la vez; git lo rechaza, y forzarlo con --force suele terminar en un lío de índices pisados. La corrección es simple: trabajá cada rama en una sola carpeta, y si necesitás otra versión, usá --detach sobre un commit puntual.

El segundo, más silencioso: crear un worktree, abrir el editor, y encontrarte con errores de módulos faltantes porque nadie corrió la instalación de dependencias en la carpeta nueva. Subís el worktree, lo abrís en tu IDE, todo tira error, revisás media hora, y al final era eso: node_modules no viaja con el checkout, hay que instalarlo de nuevo en cada carpeta.

El tercero es borrar la carpeta de un worktree a mano, con rm -rf, en vez de usar git worktree remove. Eso deja un registro huérfano en .git/worktrees que confunde a git worktree list hasta que corrés git worktree prune.

Preguntas Frecuentes

¿Qué es un git worktree?

Un git worktree es una carpeta de trabajo adicional del mismo repositorio, con su propio HEAD, su propio índice y sus propios archivos. Comparte con el worktree principal los commits, las ramas, la configuración y los hooks, y existe como comando desde git 2.5 (2015). Cubrimos ese tema en detalle en la comparativa completa entre Microsoft y Github.

¿Cómo se crea un worktree en git?

Se crea con git worktree add <ruta> <commit-ish>. Si querés que arme una rama nueva en el mismo paso, usás git worktree add -b <rama-nueva> <ruta>, y git hace el checkout automático en esa carpeta.

¿Cuál es la diferencia entre git worktree y clonar el repositorio?

Un clon crea un repositorio independiente, con su propia base de objetos y sus propias referencias, así que necesitás push y fetch para pasar commits de uno a otro. Un worktree crea otra carpeta dentro del mismo repositorio, sin duplicar el historial, y los commits se ven de inmediato entre carpetas.

¿Se puede tener la misma rama activa en dos worktrees?

No, por defecto git lo bloquea: una rama solo puede estar checkeada en un worktree a la vez. Se puede forzar con --force, pero no es recomendable porque dos carpetas terminan escribiendo sobre el mismo puntero de rama.

¿Cómo se elimina un worktree sin romper el repositorio?

Con git worktree remove <ruta>, que solo funciona si el worktree está limpio (sin archivos sin trackear ni cambios pendientes). Si borraste la carpeta a mano en vez de usar ese comando, corré git worktree prune para limpiar el registro que quedó huérfano.

Conclusión

git worktree no es una herramienta nueva, lleva desde 2015 en git 2.5, pero sigue subutilizada porque recién tiene sentido cuando entendés qué pieza del repositorio duplica y cuál comparte. La ventaja concreta frente a stash o a un clon aparte es que te da independencia de carpetas sin perder el historial compartido ni las ramas locales.

Si laburás con hotfixes frecuentes, revisás PRs seguido, o corrés agentes de código en paralelo, vale la pena sumarlo a tu flujo. Si tus cambios de contexto son cortos y sin nada a medias, un checkout común sigue siendo más simple.

Fuentes

• Documentación oficial de git-worktree – git-scm.com
• Qué es un git worktree: cómo funciona por dentro y cuándo usarlo – Ramón Chancay
• Qué es un git worktree: cómo funciona por dentro y cuándo usarlo – dev.to