Carla lleva tres días en funcionalidad/borrado-multiple. Es una rama larga: toca app.js, estilos.css y el nuevo diálogo de componentes-ui. Tiene el código a medias, con funciones sin terminar y la aplicación en un estado que ni siquiera arranca.

Y entonces llega el aviso: hay un fallo en producción y hay que publicar una corrección ahora.

Su rutina actual es esta:

Diez veces al día. Y cada vuelta tiene su peaje: el stash con ficheros sin seguimiento a veces da conflictos al recuperarlo, hay que reconstruir el contexto mental, el servidor de desarrollo se reinicia, y desde que hay submódulo (lección 06-05) cada cambio de rama arrastra además su actualización.

Su siguiente idea es clonar el repositorio dos veces. Funcionaría, pero como veremos tiene un coste real. Git ofrece algo mejor y bastante desconocido: varios directorios de trabajo compartiendo una única base de datos de objetos. Se llama git worktree, y con esta lección cerramos el módulo.

1. Qué es un worktree
2. worktree add: el primer directorio adicional
3. Comparación con clonar dos veces
4. El juego completo de comandos
5. La regla clave: una rama, un worktree
6. Cómo se ve por dentro
7. Casos de uso reales
8. Interacción con stash, submódulos y hooks
9. Cierre del módulo 6

Recordemos la estructura de la lección 01-03. Un repositorio Git tiene dos partes bien diferenciadas:

• El directorio .git/: los objetos, las referencias, la configuración, el reflog. El repositorio de verdad.
• El árbol de trabajo (working tree): los ficheros que ves y editas, que son el reflejo de un commit concreto.

Hasta ahora hemos dado por hecho que hay uno de cada. Pero no es obligatorio:

Un worktree es un directorio de trabajo adicional, con su propio HEAD, su propio índice y sus propios ficheros, que comparte la base de datos de objetos y las referencias con el repositorio original.

Lo que se comparte: objetos, ramas, etiquetas, remotos, git fetch, configuración del repositorio, reflog de las referencias.

Lo que es propio de cada worktree: HEAD, el índice, los ficheros del disco, el estado de operaciones en curso (una fusión a medias, un rebase parado) y la pila de stash.

El directorio original se llama worktree principal; los añadidos, worktrees enlazados. Funcionalmente son casi idénticos.

Carla resuelve su problema con un comando:

Lo que acaba de pasar:

• Se ha creado el directorio ~/proyectos/gestor-tareas-urgente/.
• Contiene una copia de trabajo completa del proyecto en el estado de main.
• Se ha creado la rama correccion/urgente a partir de main y está activa allí.
• El directorio original no se ha tocado en absoluto: sigue en funcionalidad/borrado-multiple, con todo su trabajo a medias intacto.

Ahora Carla trabaja en el segundo directorio con total normalidad:

Y cuando termina, vuelve:

Exactamente como lo dejó. Ni stash, ni pop, ni reconstruir el contexto: el editor, el servidor de desarrollo y la ventana del navegador siguen abiertos donde estaban.

Las formas de invocar add:

Y una útil cuando la rama viene del remoto:

Git detecta que funcionalidad/exportar existe en origin y crea automáticamente una rama local con seguimiento (el comportamiento de --guess-remote, que se puede fijar con git config worktree.guessRemote true).

La alternativa evidente era git clone otra vez. La comparación explica por qué worktree es mejor casi siempre:

El punto que más se subestima es "un commit en A, ¿visible en B?". Con dos clones, para llevar un commit de uno a otro hay que pasar por el servidor. Con worktrees, en cuanto Carla confirma en un directorio, ese commit ya existe para el otro: puede hacer git cherry-pick, git rebase o git log sobre él inmediatamente, sin red de por medio.

El ahorro de espacio, con cifras: si .git/ ocupa 400 MB (historial largo, algún binario) y el árbol de trabajo 15 MB, un clon extra cuesta 415 MB y un worktree 15 MB. En repositorios grandes la diferencia deja de ser anecdótica.

Antes existía git clone --shared / --reference para compartir objetos entre clones. Funciona, pero es frágil: si el repositorio de referencia se mueve o se limpia, el clon dependiente puede quedar corrupto. git worktree es la solución moderna y segura al mismo problema, y la que debe usarse.

La marca prunable indica que el directorio ya no existe en el disco y su registro se puede limpiar.

La forma correcta de eliminar un worktree:

Borra el directorio y su registro. Si hay cambios sin confirmar, se niega —lo cual es una protección, no una molestia:

Y ojo: remove no borra la rama. Eso es aparte:

Si borraste el directorio a mano con rm -rf (que funciona, pero deja el registro), prune limpia los restos:

Git también lo ejecuta solo de vez en cuando, y el plazo de gracia se controla con gc.worktreePruneExpire (por defecto, tres meses).

Mueve el directorio y actualiza las rutas internas. Moverlo con mv a secas rompe los enlaces, así que usa siempre este comando.

Un worktree bloqueado no se puede prune ni move. Es exactamente para el caso de un worktree en una unidad extraíble o un recurso de red: cuando la unidad no está montada, el directorio "no existe" y prune lo borraría del registro sin más. lock lo impide, y el motivo aparece en git worktree list --porcelain para que se sepa por qué.

Reconstruye los enlaces internos cuando algo los ha roto: has movido directorios a mano, has restaurado una copia de seguridad, o has renombrado el repositorio principal.

Tabla resumen:

Esta es la restricción fundamental, y hay que entenderla porque explica la mitad de los mensajes de error que verás:

Una misma rama no puede estar activa en dos worktrees a la vez.

Y lo mismo al crear:

Por qué existe la restricción. Una rama es un puntero que avanza al confirmar (lección 03-01). Si dos worktrees tuvieran la misma rama activa, un commit en uno movería la rama bajo los pies del otro: el segundo se encontraría con que su HEAD apunta a un commit que él no ha creado, y su árbol de trabajo dejaría de corresponder a nada coherente. Git prohíbe la situación en lugar de dejar que ocurra.

No es una limitación, es una protección. Y tiene tres salidas cuando de verdad necesitas el mismo código dos veces:

La opción A es la que más se usa: para leer o compilar una rama no hace falta tenerla activa como rama.

Y una consecuencia práctica que conviene saber: git branch -d se niega a borrar una rama que esté activa en otro worktree, y git rebase o git merge tampoco pueden operar sobre ella desde fuera. Para localizar dónde está:

Retomamos la lección 01-04 y el modelo de datos, porque el mecanismo es elegante y explica todo lo anterior.

En el worktree principal, .git es un directorio:

En un worktree enlazado, .git es un fichero de texto:

Una sola línea que dice: "mi repositorio está allí". Es exactamente el mismo mecanismo que usan los submódulos de la lección 06-05, donde el .git del submódulo es un fichero que apunta a .git/modules/<nombre> del padre.

Y en el repositorio principal:

Y ahí está la explicación completa del modelo:

• HEAD e index están por worktree → cada uno puede estar en una rama distinta y tener sus propios cambios preparados.
• objects/ y refs/ están en el commondir → las ramas, las etiquetas y los objetos son los mismos para todos, y por eso un commit en uno es visible al instante en el otro.

Con esto se entiende también por qué la restricción del apartado 5 es inevitable: hay un solo fichero refs/heads/funcionalidad/borrado-multiple, y no puede ser el HEAD de dos directorios que confirman por separado.

Hay incluso una notación para consultar el HEAD de otro worktree:

Y una nota sobre configuración: por defecto, .git/config es compartido por todos los worktrees. Si necesitas que uno tenga configuración propia, existe extensions.worktreeConfig:

Es un caso avanzado y poco frecuente, pero conviene saber que existe si te encuentras con un config.worktree dentro de .git/worktrees/<nombre>/.

El de Carla, y el más común. Un worktree permanente para urgencias:

Cuando llega el aviso, cd ../gestor-tareas-hotfix, git pull, se crea la rama, se arregla y se publica. Sin stash, sin cambiar de rama, sin perder el contexto.

Bruno tiene que comprobar si un problema de rendimiento existía en la versión 1.0:

Dos servidores, dos pestañas del navegador, las dos versiones funcionando a la vez. Comparar así es incomparablemente más fiable que ir alternando ramas y recordar cómo era.

Una compilación completa de gestor-tareas tarda cuatro minutos. Con un solo directorio, esos cuatro minutos son de espera, porque cualquier edición ensucia el resultado. Con worktrees:

Ana tiene que revisar la pull request de Bruno, pero está a mitad de su propio trabajo:

Sin --detach funcionaría también, pero para revisar no hace falta rama local, y así se evita acumular ramas de revisión.

Un git rebase -i con conflictos (lección 05-02) deja el repositorio en un estado intermedio. Si aparece algo urgente, estás atrapado: rebase --abort y a empezar de nuevo. Con un worktree dedicado, el rebase se queda parado en su directorio y tú trabajas en otro. Como el estado de las operaciones en curso es propio de cada worktree, no interfieren.

git bisect (lección 06-02) hace decenas de checkout en tu directorio. Si es una bisección larga con compilaciones, puedes lanzarla en un worktree aparte:

Mientras tanto, tu directorio principal sigue en tu rama, intacto. Al terminar, git bisect reset y git worktree remove.

Algunos proyectos publican la documentación en una rama independiente (gh-pages y similares). Con worktrees:

Se edita la documentación en su directorio y el código en el suyo, con historiales separados y sin cambiar de rama nunca.

La pila de stash es propia de cada worktree. Un git stash list en el directorio principal no muestra lo guardado en otro:

Técnicamente, refs/stash se guarda por worktree. Es coherente con el modelo —el stash es trabajo a medias de un árbol concreto— pero sorprende la primera vez.

Y la conclusión práctica de todo esto: los worktrees no sustituyen a stash, sino que reducen mucho la necesidad de usarlo. stash sigue siendo la herramienta correcta para apartar algo durante dos minutos dentro de la misma rama; el worktree lo es para trabajar en dos ramas durante días.

Los worktrees y los submódulos (lección 06-05) conviven, pero hay que saber dos cosas:

• Los submódulos no se inicializan solos en un worktree nuevo. Después del add, toca:

• Los repositorios internos de los submódulos viven en el .git/modules/ común, así que los objetos se comparten igual que los del padre: la inicialización no vuelve a descargar nada de la red, solo hace checkout. Es rápida.

El soporte de worktrees dentro de submódulos ha mejorado mucho en las versiones recientes de Git, pero sigue siendo el terreno donde más rarezas aparecen. Si algo se descoloca, git worktree repair suele arreglarlo.

Los hooks son compartidos: hay un solo .git/hooks/ (o un solo core.hooksPath, lección 06-01) para todos los worktrees. Un pre-commit instalado funciona en todos automáticamente, lo cual es una ventaja.

El matiz: un hook que asuma rutas absolutas o que dé por hecho un directorio concreto puede confundirse. Los hooks se ejecutan con el directorio de trabajo puesto en la raíz del worktree activo, así que usar rutas relativas es lo correcto. Y si un hook necesita distinguir dónde está:

Un apunte breve, porque el tema completo es de otra lección: los worktrees comparten la base de objetos, así que un git gc afecta a todos y Git tiene cuidado de no eliminar objetos referenciados desde cualquiera de ellos. Un worktree registrado pero cuyo directorio ya no existe puede, en cambio, mantener vivos objetos innecesariamente: por eso conviene ejecutar git worktree prune de vez en cuando.

Todo lo relativo a git gc, git maintenance y el rendimiento en repositorios grandes es el tema de la lección 08-06: Consejos de Rendimiento; los clones parciales, sparse-checkout y las técnicas de escalado, el de la 10-04.

Con esta lección cierras el bloque de herramientas. Repasando lo que ha cambiado en la forma de trabajar del equipo de gestor-tareas:

• Hooks (06-01): comprobaciones automáticas en pre-commit, commit-msg y pre-push, versionadas con core.hooksPath. Ayudan contra el despiste, pero lo obligatorio se comprueba en el servidor.
• git bisect (06-02): búsqueda binaria que convierte 214 commits en 8 pruebas, automatizable con bisect run y sus códigos de salida.
• git blame (06-03): la historia de cada línea, con -w, -C e --ignore-rev para atravesar el ruido, y git log -L para ver la evolución completa.
• git log avanzado y alias (06-04): --graph, --first-parent, --simplify-by-decoration, --left-right, formatos con colores, shortlog, y los alias que convierten todo eso en una palabra.
• Submódulos (06-05): un puntero a un commit de otro repositorio, con reproducibilidad exacta a cambio de fricción, y comparados con subtree, paquetes y monorepo.
• git worktree (06-06): varios directorios de trabajo sobre una única base de objetos.

Y una idea que atraviesa todo el módulo: el historial de Git no es solo un registro de lo que pasó, es una base de datos consultable. Quién escribió cada línea, en qué commit cambió un comportamiento, qué se ha integrado en main este mes, qué versión exacta de la biblioteca usaba la versión 1.0. Todas esas preguntas tienen respuesta exacta, y ahora sabes cómo pedirla.

El equipo domina la herramienta. Ana, Bruno y Carla saben construir el historial, manipularlo con criterio, consultarlo a fondo y automatizar comprobaciones sobre él.

Lo que no han acordado todavía es cómo trabajar juntos. Y esas preguntas ya no son técnicas:

• Cuando Bruno termina una funcionalidad, ¿cómo la propone? ¿Empuja directamente a main? ¿Abre una pull request? ¿Y si no tiene permiso de escritura en el repositorio?
• Cuando Ana revisa el trabajo de Carla, ¿qué mira, cómo comenta y cuándo aprueba? ¿Qué hace un revisor que no sea repetir lo que ya dice el linter?
• ¿Qué ramas existen y para qué sirve cada una? ¿Hay una rama develop? ¿Ramas de versión? ¿O todo el mundo integra en main varias veces al día?
• ¿Cuándo se publica una versión? ¿Qué hay que haber pasado antes de que un cambio llegue a producción?

No hay una respuesta única: hay flujos de trabajo distintos, cada uno con su lógica, sus ventajas y su tipo de equipo. Un proyecto de código abierto con cientos de colaboradores externos no puede funcionar como un equipo de tres personas que despliega cinco veces al día.

En el módulo 7: Estrategias de Colaboración y Flujo de Trabajo veremos los forks y las pull requests como mecanismo para proponer cambios, las revisiones de código y cómo se hacen bien, y los tres grandes modelos de ramificación —Git Flow, GitHub Flow y Trunk Based Development— comparados con criterio para saber cuál encaja en cada situación. Y cerraremos con la integración continua: las comprobaciones automáticas que, esta vez sí, nadie puede saltarse con un --no-verify.

Empezamos por cómo se propone un cambio, en la lección 07-01: Forks y Pull Requests.

Error 1: intentar abrir la misma rama en dos worktrees. Git lo impide y te dice dónde está activa. Usa --detach si solo quieres leer o compilar.

Error 2: borrar el directorio con rm -rf. Funciona, pero deja el registro sucio. Usa git worktree remove, o git worktree prune después.

Error 3: mover el directorio con mv. Rompe los enlaces internos. Usa git worktree move, o git worktree repair si ya lo hiciste.

Error 4: olvidar que remove no borra la rama. Quitar el worktree deja la rama viva; bórrala aparte con git branch -d.

Error 5: esperar que los submódulos se inicialicen solos. Hay que ejecutar git submodule update --init --recursive en cada worktree nuevo.

Error 6: buscar un stash en el worktree equivocado. La pila es propia de cada uno. Si no aparece, mira en el otro directorio.

Error 7: crear worktrees dentro del propio repositorio. git worktree add ./temporal funciona, pero el directorio aparece como contenido sin seguimiento del repositorio principal. Créalos fuera, como hermanos del directorio original.

Error 8: acumular worktrees olvidados. Ocupan disco y mantienen ramas ocupadas. git worktree list de vez en cuando, y remove de los que sobran.

Consejo 1: adopta una convención de nombres. gestor-tareas, gestor-tareas-hotfix, gestor-tareas-v1. Con ../<proyecto>-<propósito> nunca te pierdes.

Consejo 2: ten un worktree permanente para urgencias. Siempre en main, siempre limpio. Es el que más veces te salvará el día.

Consejo 3: crea un alias. Con lo aprendido en la lección 06-04:

git nuevo correccion-urgente crea ../gestor-tareas-correccion-urgente con esa rama.

Consejo 4: --detach para todo lo que sea solo lectura. Revisar, compilar, comparar o bisecar no necesita rama local, y así no te chocas con la regla de una rama por worktree.

Consejo 5: un git fetch basta para todos. Es un solo repositorio: no repitas el fetch en cada directorio.

Consejo 6: comprueba tu versión de Git. worktree existe desde la 2.5, pero move, remove y repair llegaron después (2.17 y 2.30). En versiones antiguas, algunas operaciones son manuales.

1. Crea un repositorio con main y una rama funcionalidad/larga con cambios sin confirmar (modificados y sin seguimiento).
2. Sin hacer stash, crea un worktree en ../proyecto-hotfix con una rama nueva correccion/urgente desde main.
3. Confirma una corrección en el worktree nuevo.
4. Vuelve al directorio original y comprueba que tus cambios sin confirmar siguen exactamente igual.
5. Comprueba desde el directorio original que el commit del hotfix ya existe (git log correccion/urgente), sin haber hecho ningún push ni fetch.
6. Elimina el worktree y la rama.

1. Con el repositorio anterior, intenta crear un worktree con una rama que ya esté activa en otro. Anota el mensaje de error.
2. Consigue el mismo código en un segundo directorio usando --detach.
3. Comprueba con git worktree list que uno aparece con rama y el otro como (detached HEAD).
4. Intenta borrar con git branch -d una rama activa en otro worktree y observa qué pasa.

1. En un worktree enlazado, comprueba que .git es un fichero y muestra su contenido.
2. Localiza el directorio correspondiente en .git/worktrees/ del principal y lista su contenido.
3. Compara el HEAD de ambos worktrees.
4. Haz un git stash en uno y comprueba que git stash list en el otro está vacío.
5. Borra un worktree con rm -rf, comprueba que sigue apareciendo en git worktree list (marcado como prunable) y límpialo con prune.

Solución 1:

Intactos. Ni stash ni pop.

El commit hecho en el otro directorio es visible inmediatamente: es la misma base de objetos. Con dos clones habría hecho falta push + fetch.

La rama sigue viva: remove no la borra.

Solución 2:

Mismo commit, mismo contenido, sin conflicto: en ../otro no hay ninguna rama que pueda moverse.

Git protege la rama activa en cualquier worktree, no solo en el actual.

Solución 3:

El worktree enlazado tiene un hash directo (detached), el principal una referencia simbólica a su rama, y commondir apunta al .git compartido donde están los objetos y las refs.

El registro sigue ahí, marcado como prunable.

Limpio. Con git worktree remove en lugar de rm -rf, este último paso no habría hecho falta.

git worktree resuelve un problema cotidiano con una idea simple y bien construida. Lo esencial:

• Un worktree es un directorio de trabajo adicional con su propio HEAD e índice, que comparte objetos y referencias con el repositorio original.
• Frente a clonar dos veces: no duplica la base de objetos, comparte ramas, etiquetas, remotos y hooks, un solo fetch sirve para todos, y un commit hecho en uno es visible al instante en el otro, sin pasar por el servidor.
• git worktree add <ruta> [<rama>] lo crea en segundos; -b crea rama nueva y --detach abre un commit sin rama.
• El juego completo es add, list, remove, prune, move, lock/unlock y repair. Usa remove en lugar de rm -rf y move en lugar de mv; lock protege los worktrees en unidades extraíbles.
• Una rama no puede estar activa en dos worktrees a la vez. No es una limitación caprichosa: evita que un commit mueva la rama bajo los pies de otro directorio. La salida para lectura y compilación es --detach.
• Por dentro, el .git del worktree enlazado es un fichero con una línea gitdir: que apunta a .git/worktrees/<nombre>, donde viven su HEAD, su index y su reflog; los objetos y las refs están en el commondir compartido. Es el mismo mecanismo que usan los submódulos.
• Casos de uso que se ganan el sitio: hotfix sin perder el contexto, comparar dos versiones en ejecución, compilar una rama mientras trabajas en otra, revisar la rama de un compañero, y aislar un rebase largo o una bisección.
• El stash es propio de cada worktree; los hooks son compartidos; los submódulos hay que inicializarlos en cada worktree nuevo.
• Y la relación con stash: no lo sustituye, pero reduce mucho su uso. stash para minutos dentro de una rama; worktree para días entre varias.

Con esto se cierra el módulo 6 y el bloque técnico del curso. El equipo de gestor-tareas ya sabe construir, manipular, consultar y automatizar su historial. Lo que necesita ahora es ponerse de acuerdo: cómo se propone un cambio, cómo se revisa y qué flujo de ramas seguir. Eso es el módulo 7, y empieza en la lección 07-01: Forks y Pull Requests.