Un git worktree es un directorio de trabajo adicional del mismo repositorio: una segunda carpeta con sus propios archivos, su propia rama activa y su propio staging, que comparte con la carpeta original el historial, las ramas y la configuración. Con él puedes tener main abierta en una carpeta y feature/login en otra al mismo tiempo, sin clonar el repositorio dos veces y sin hacer stash cada vez que cambias de tarea. El comando existe desde git 2.5 (2015), pero es fácil pasarlo por alto porque solo tiene sentido cuando sabes cómo está hecho un repositorio por dentro: qué se comparte entre carpetas y qué no.
TL;DR
- Un git worktree es otra carpeta de trabajo del mismo repositorio: tiene su propio
HEAD, su índice y sus archivos, pero comparte los commits, las ramas, la configuración y los hooks con el worktree principal.- Un git worktree vinculado no tiene una carpeta
.gitsino un archivo.gitde una línea que apunta a.git/worktrees/<nombre>, donde git guarda lo que es propio de ese worktree. Por eso crearlo es rápido y no duplica el historial.- Un git worktree tiene dos límites que conviene conocer: una rama solo puede estar activa en un worktree a la vez, y no copia lo que git no versiona (
node_modules,.env, builds).
Qué es un git worktree
Un git worktree es un directorio de trabajo adicional del mismo repositorio, con su propia rama activa, su HEAD y su índice; los commits, las ramas y la configuración se comparten con el worktree principal.
El problema que resuelve es concreto. Un repositorio recién clonado tiene una sola carpeta de trabajo, y en esa carpeta solo puede estar activa una rama a la vez. Si estás a mitad de feature/payments y te piden revisar un bug en main, tienes tres opciones, y ninguna es cómoda: hacer un commit temporal, guardar los cambios con git stash, o clonar el repositorio otra vez en otra carpeta. Las dos primeras te obligan a interrumpir lo que estabas haciendo; la tercera duplica el historial completo y crea un repositorio aparte que no ve tus ramas locales.
git worktree agrega una cuarta opción: añadir una segunda carpeta de trabajo al mismo repositorio. En esa carpeta abres main, arreglas el bug y haces commit, mientras feature/payments sigue intacta en la carpeta original, con sus cambios a medias. Las dos carpetas leen y escriben en la misma base de datos de git, así que el commit que hiciste en una aparece de inmediato en la otra.
Para entender por qué eso funciona, y qué se comparte exactamente, hay que separar las piezas de un repositorio.
Las tres piezas de un repositorio git
Un repositorio git tiene tres piezas: la base de objetos (el historial), las referencias (las ramas y tags que apuntan a ese historial) y el estado de trabajo (la rama activa, el índice y los archivos de la carpeta).
| Pieza | Qué contiene | Dónde vive |
|---|---|---|
| La base de objetos | Todos los commits, árboles y contenidos de archivos del historial | .git/objects |
| Las referencias | Los nombres que apuntan a commits: ramas (refs/heads/main), tags, ramas remotas |
.git/refs y .git/packed-refs
|
| El estado de trabajo | Qué rama tienes activa (HEAD), qué preparaste para el próximo commit (el índice) y los archivos que ves en la carpeta |
.git/HEAD, .git/index y el directorio de trabajo |
Las dos primeras piezas son el repositorio en sí: el historial y los nombres que apuntan a él. La tercera es tu posición dentro de ese historial: en qué rama estás, qué archivos tienes desplegados y qué cambios preparaste. Un repositorio normal tiene una sola copia de cada pieza, y por eso solo puedes estar en un lugar a la vez.
Un worktree duplica solo la tercera pieza. Cada worktree tiene su propio HEAD, su propio índice y su propia carpeta de archivos, pero todos comparten la base de objetos y las referencias.
Los worktrees tienen nombre según su origen. La carpeta donde clonaste o iniciaste el repositorio, la que contiene la carpeta .git de verdad, es el worktree principal (main worktree). Las que añades con git worktree add son worktrees vinculados (linked worktrees). Funcionan igual para el día a día; la diferencia es que el principal no se puede borrar ni mover con git worktree, porque es donde vive el repositorio.
Sigue leyendo
Hasta aquí la primera mitad. El recorrido completo — con el resto de la implementación, las decisiones de diseño y lo que solo aparece en producción — está en mi blog:
Lee el artículo completo en ramonchancay.me →
Publicado originalmente en www.ramonchancay.me/es/blog/que-es-un-git-worktree.
Top comments (0)