Git Worktrees: la feature oculta de Git para trabajar en varias ramas sin stash

Imaginá esta escena: estás a la mitad de una feature grande en la rama feature/checkout-v2 con cambios sin commitear, y entra un bug crítico en producción. La opción típica es git stash, cambiar de rama, arreglar, volver, hacer git stash pop y cruzar los dedos. Git tiene una solución más limpia desde hace años y casi nadie la usa: git worktree.

Qué es un worktree

Un worktree (árbol de trabajo) es un directorio adicional asociado al mismo repositorio donde podés tener otra rama distinta checkout. Normalmente cuando clonás un repo, tenés un solo directorio con un solo checkout: esa es la worktree principal. El comando git worktree add crea worktrees adicionales (enlazadas) que comparten el mismo objeto .git pero tienen su propio HEAD, índice y archivos de trabajo. En términos prácticos: podés tener la rama main en /proyectos/app, la rama feature/checkout-v2 en /proyectos/app-checkout y la rama hotfix/bug-pago en /proyectos/app-hotfix — las tres trabajando al mismo tiempo sobre un único repositorio. Sin stash, sin branches a medio commitear, sin pérdida de contexto.

El caso de uso típico: hotfix sin interrumpir

Estás en feature/checkout-v2 con cambios sin commitear. Llega el bug. En vez de stashear:

⏱️ Lectura: 4 min

# Crear una worktree nueva con una rama nueva basada en main
git worktree add -b hotfix/bug-pago ../app-hotfix main

# Cambiar al directorio de la nueva worktree
cd ../app-hotfix

# Arreglar, commitear, pushear
vim src/pagos/process.js
git commit -am "fix: corregir validacion de monto"
git push origin hotfix/bug-pago

# Volver al trabajo original (sin tocar el stash)
cd ../app

# Cuando termine el hotfix, limpiar
git worktree remove ../app-hotfix

Tu rama feature/checkout-v2 siguió intacta en ../app todo el tiempo. Tus cambios sin commitear ahí siguen. Cero interrupciones.

Los ocho subcomandos de git worktree

Según la documentación oficial, git worktree expone ocho subcomandos:

• add — crear una worktree nueva. Soporta -b para crear rama nueva, --detach para HEAD suelto, --orphan para árbol vacío.
• list — listar todas las worktrees. Con -v muestra más detalle; con --porcelain output parseable por scripts.
• remove — eliminar una worktree limpia (sin cambios sin commitear). Con -f fuerza.
• move — mover una worktree a otra ubicación.
• lock / unlock — bloquear/desbloquear una worktree para que no sea eliminada por prune. Útil si la tenés en un disco externo desconectable.
• prune — limpiar metadatos de worktrees que ya no existen. Con -n hace dry-run.
• repair — reparar metadatos si moviste archivos manualmente.

Reglas importantes y gotchas

• Una rama, una worktree — Git no te deja tener la misma rama checkout en dos worktrees simultáneamente. Si intentás, te dará error. Esto previene conflictos de índice.
• Usa –detach para commits sueltos — si querés revisar un commit viejo sin rama asociada: git worktree add --detach ../review abc123.
• remove no borra sin pedir confirmación — git worktree remove falla si hay cambios sin commitear. Usá -f solo si sabés lo que hacés.
• El .git es un archivo, no un directorio — en una worktree enlazada, .git es un archivo de texto que apunta al repositorio principal. Muchos scripts que asumen .git/ como directorio se rompen. Tenelo en cuenta si usás hooks caseros.

Cuándo conviene usarlo

Git worktree brilla en estos escenarios:

• Hotfixes sin interrumpir feature work — el caso ejemplo de arriba.
• Code review — tener el PR ajeno checkout en ../app-review mientras seguís codeando en el tuyo.
• Builds largos en paralelo — dos worktrees, dos builds simultáneos de ramas distintas, sin bloqueo.
• Comparar implementaciones — tener dos ramas alternativas abiertas lado a lado para diff visual entre editores.
• AI coding con múltiples ramas — herramientas como Claude Code soportan worktrees para que un agente trabaje en una rama mientras vos seguís en otra.

Comandos cotidianos para tener a mano

# Listar todas tus worktrees
git worktree list

# Crear worktree con rama nueva
git worktree add -b nueva-rama ../carpeta

# Crear worktree desde rama existente
git worktree add ../carpeta nombre-rama

# Crear worktree en HEAD suelto (solo lectura)
git worktree add --detach ../carpeta commit-sha

# Borrar worktree limpia
git worktree remove ../carpeta

# Limpiar metadatos huerfanos
git worktree prune -v

Conclusión

Git worktree lleva en Git desde la versión 2.5 (2015) y sigue siendo una de las features más infrautilizadas del ecosistema. Reemplaza el 90% de los usos de git stash y elimina la frustración de perder contexto cada vez que hay que cambiar de rama. Si tu flujo es «cambio constante entre ramas», dedicale 10 minutos esta semana a incorporarlo — te va a ahorrar horas después.  

📱 ¿Te gusta este contenido? Únete a nuestro canal de Telegram @programacion donde publicamos a diario lo más relevante de tecnología, IA y desarrollo. Resúmenes rápidos, contenido fresco todos los días.

📑 En este artículo

1. Qué es un worktree
2. El caso de uso típico: hotfix sin interrumpir
3. Los ocho subcomandos de git worktree
4. Reglas importantes y gotchas
5. Cuándo conviene usarlo
6. Comandos cotidianos para tener a mano
7. Conclusión