Llevas tres archivos editados en una rama de feature, sin nada confirmado, cuando un compañero te avisa de un null pointer en producción. El movimiento habitual es hacer git stash, cambiar a main, arreglarlo, hacer push, y luego git stash pop con la esperanza de que nada de tu feature a medias dependiera de los archivos que acabas de tocar. git worktree evita todo ese baile. Hace checkout de la rama del hotfix en una segunda carpeta, junto a la de tu feature, y ambas comparten el mismo repositorio.

Qué hace realmente git worktree

Un checkout normal te da los archivos de una sola rama a la vez. Cambiar de rama reescribe esos archivos en el mismo sitio. git worktree te da varios checkouts del mismo repositorio, cada uno en su propio directorio con su propia rama, y puedes editarlos de forma independiente.

No son clones independientes. Existe un único directorio .git con la base de objetos, las refs y la configuración, y todos los worktrees leen y escriben en él. En un worktree secundario, .git ni siquiera es un directorio: es un archivo de una línea que apunta al compartido. Por eso crear un worktree es casi instantáneo y no añade historial en disco.

Hay una restricción que importa. Dos worktrees no pueden tener la misma rama en checkout a la vez: una rama solo apunta a un commit actual, y si dos checkouts hicieran commits sobre ella competirían por mover ese mismo puntero. Todo lo demás es independiente en cada worktree: los archivos sin seguimiento, el index, y en qué commit está HEAD.

Cómo crear un worktree para un hotfix

Desde tu checkout actual de myapp, en feature/checkout-flow con cambios sin confirmar:

1

git worktree add ../myapp-hotfix -b hotfix/null-pointer main

Esto crea ../myapp-hotfix junto a tu directorio actual, con una rama nueva hotfix/null-pointer creada desde main y ya en checkout ahí mismo. Tu directorio original se queda en feature/checkout-flow, con los cambios sin confirmar intactos.

1
2
3
4

cd ../myapp-hotfix
# fix the bug, commit, push
git push -u origin hotfix/null-pointer
cd ../myapp

De vuelta en el directorio original, tu trabajo de feature está exactamente como lo dejaste. Nada que hacer pop, ningún stash que se te pueda olvidar.

Sin -b, git worktree add <path> nombra la rama según el último componente de la ruta. Si no existe una rama con ese nombre, Git la crea desde HEAD; si existe y no está en checkout en otro worktree, Git la usa directamente. Usa -d (--detach) cuando quieras explorar un commit sin ninguna rama de por medio.

Cómo listar, eliminar y limpiar worktrees

1

git worktree list

1
2

/home/user/myapp          3a1f9c2 [feature/checkout-flow]
/home/user/myapp-hotfix   7e04d81 [hotfix/null-pointer]

Una vez que el hotfix esté fusionado, elimina el worktree a través de Git en vez de borrar la carpeta a mano:

1

git worktree remove ../myapp-hotfix

remove se niega si el worktree tiene archivos rastreados modificados o archivos sin seguimiento. Pasa -f para forzarlo. Si el directorio desaparece de otra forma (un rm -rf por accidente, un job de CI que se cae), Git conserva su entrada administrativa y git worktree list sigue mostrándola. Elimina esa entrada obsoleta con:

1

git worktree prune

Ejecútalo primero con -n para ver qué eliminaría.

Algunos worktrees tienen que durar semanas: una rama de release de larga duración, o un checkout en una unidad de red que no siempre está montada. Bloquéalos para que prune deje su entrada en paz y move y remove se nieguen a tocarlos:

1
2

git worktree lock --reason "release branch, do not prune" ../myapp-release
git worktree unlock ../myapp-release

Desbloquéalo primero si quieres reubicar uno con git worktree move <path> <new-path>. Mover o eliminar un worktree bloqueado sin desbloquearlo exige --force dos veces, pensado para que sea una decisión deliberada y no un accidente.

Cuándo usar git worktree además de para hotfixes

Cualquier momento en el que necesites dos checkouts activos en vez de uno:

  • Revisar un PR sin perder tu sitio. git worktree add ../myapp-review origin/some-pr-branch te da una copia que puedes compilar de la rama de otra persona, mientras tu propio trabajo sigue en checkout donde estaba.
  • Ejecutar git bisect sin bloquear todo lo demás. Un bisect mueve HEAD en cada paso, así que el checkout donde corre queda inservible para cualquier otra cosa hasta que termines o hagas reset. Ejecútalo en un worktree dedicado (ver Git Bisect: Cómo Encontrar el Commit que Rompió tu Código) y sigue trabajando en el principal.
  • Ejecutar dos tareas contra el repositorio en paralelo. Una suite de pruebas larga en una rama mientras editas otra, o dos agentes de IA trabajando en tareas separadas: cada uno necesita su propio directorio de trabajo. Un worktree da uno sin un segundo git clone ni una segunda carpeta .git de varios gigabytes.

Cuándo no usar git worktree

Cada worktree duplica el working tree, no la base de objetos. Diez worktrees de un repositorio con un checkout de 50 MB cuestan unos 500 MB de archivos en disco, aunque haya un solo .git. Para un cambio de contexto de cinco minutos, git stash sale más barato y no deja nada que limpiar después.

Los submódulos son el punto delicado. git worktree move no mueve un worktree que contenga submódulos, y un worktree nuevo arranca con sus directorios de submódulos vacíos hasta que ejecutas git submodule update --init dentro de él. La propia documentación de Git califica de incompleto el soporte de submódulos en checkouts múltiples, así que para un superproyecto con muchos submódulos un clon separado es la opción más segura.

Algunas herramientas también asumen un único directorio de trabajo por repositorio. Un IDE o un file-watcher que indexa su caché según la ruta absoluta del repositorio puede confundirse al ver el mismo historial en dos sitios. Abrir cada worktree como su propio proyecto, no como una subcarpeta del primero, suele resolverlo.

Si solo necesitas guardar o deshacer algo en el checkout que ya tienes, git stash o git reset, revert o restore es la herramienta más ligera. La próxima vez que un hotfix aparezca a mitad de una feature, prueba git worktree add antes que git stash y compara cuál de los dos te cuesta menos limpiar después.

Artículos relacionados