git worktree: trabaja en varias ramas a la vez sin stash ni commits basura
Deja de hacer stash o commits a medias cada vez que necesitas cambiar de rama. Con git worktree puedes tener múltiples ramas abiertas simultáneamente en carpetas separadas, compartiendo el mismo repositorio. Guía práctica con comandos, casos de uso reales y errores que debes evitar
Por Equipo Starbyte
git worktree: trabaja en varias ramas a la vez sin stash ni commits basura
Estás a mitad de un refactor complejo en tu rama feature/nueva-api cuando llega un mensaje: "Hay un bug en producción, ¿puedes revisarlo?". Tu flujo habitual probablemente es algo así:
git stash
git checkout main
git checkout -b hotfix/login-error
# ... arreglas el bug, haces commit, push, PR ...
git checkout feature/nueva-api
git stash pop
# ... rezas para que el stash no tenga conflictos
Esto funciona, pero es frágil, lento y rompe tu concentración. git worktree lo resuelve de raíz: te permite tener varias ramas del mismo repositorio abiertas en carpetas separadas, al mismo tiempo.
Qué es git worktree
Cada repositorio Git tiene un árbol de trabajo principal: la carpeta donde editas archivos. Un worktree es un árbol de trabajo adicional, vinculado al mismo repositorio. Tiene su propia rama, su propio staging area y sus propios archivos en disco, pero comparte la misma base de datos de objetos, historial y configuración.
La estructura se ve así:
mi-proyecto/ ← worktree principal (rama main)
├── src/
├── .git/ ← repositorio compartido
│
../mi-proyecto-hotfix/ ← worktree vinculado (rama hotfix/login)
├── src/
└── .git ← archivo (no carpeta), apunta al .git principal
No es un clon. No duplica datos. Los commits que hagas en cualquier worktree son visibles inmediatamente desde todos los demás.
Requisitos
- Git 2.5 o superior (lanzado en 2015, así que casi seguro ya lo tienes).
- Verifica con:
git --version
Comandos esenciales
Crear un worktree para una rama existente
git worktree add ../hotfix-login hotfix/login-error
Esto crea la carpeta ../hotfix-login con la rama hotfix/login-error ya en checkout. Puedes abrir esa carpeta en tu editor y trabajar directamente.
Crear un worktree con una rama nueva
git worktree add -b feature/dashboard ../dashboard main
Crea la rama feature/dashboard a partir de main y la deja lista en ../dashboard.
Forma más rápida (rama automática)
git worktree add ../hotfix
Si no especificas rama, Git crea automáticamente una nueva rama llamada hotfix (toma el nombre de la carpeta).
Listar worktrees activos
git worktree list
Salida ejemplo:
/home/dev/mi-proyecto a3f9c81 [main]
/home/dev/hotfix-login b7d4e92 [hotfix/login-error]
/home/dev/dashboard c1e8f03 [feature/dashboard]
Eliminar un worktree
Cuando termines con la rama, no borres la carpeta manualmente. Usa:
git worktree remove ../hotfix-login
Si tiene cambios sin commitear, Git te pedirá confirmación. Puedes forzarlo con --force.
Limpiar worktrees huérfanos
Si borraste una carpeta de worktree manualmente (con rm -rf), limpia las referencias internas:
git worktree prune
Cuándo usar worktree (y cuándo no)
| Situación | ¿Worktree? | Alternativa |
|---|---|---|
| Hotfix urgente mientras trabajas en un feature | Sí | — |
| Revisar un PR de un compañero sin perder tu contexto | Sí | — |
| Trabajar en dos features en paralelo por días | Sí | — |
| Ejecutar tests largos en una rama mientras programas en otra | Sí | — |
| Cambio rápido de menos de 10 minutos | No | git stash o git checkout |
| Solo necesitas ver un archivo de otra rama | No | git show otra-rama:archivo.js |
Flujo de trabajo real: hotfix sin interrumpir tu feature
# 1. Estás en mi-proyecto/, rama feature/nueva-api
# 2. Creas un worktree para el hotfix
git worktree add -b hotfix/bug-critico ../hotfix main
# 3. Abres la carpeta en otra ventana del editor
cd ../hotfix
# 4. Arreglas, commiteas, haces push
git add .
git commit -m "fix: corregir error de autenticación en login"
git push origin hotfix/bug-critico
# 5. Vuelves a tu feature (sigue exactamente como la dejaste)
cd ../mi-proyecto
# 6. Cuando el hotfix se mergea, eliminas el worktree
git worktree remove ../hotfix
Tu rama feature/nueva-api nunca se tocó. No hubo stash. No hubo commits temporales. No hubo conflictos al volver.
Flujo avanzado: worktree para code review
# Tu compañero te pide revisar su PR en la rama feature/pagos
git fetch origin
git worktree add ../review-pagos origin/feature/pagos
# Abres ../review-pagos en tu IDE, revisas, ejecutas tests
cd ../review-pagos
npm install
npm test
# Terminas la revisión y limpias
cd ../mi-proyecto
git worktree remove ../review-pagos
Errores comunes
Intentar hacer checkout de la misma rama en dos worktrees. Git no lo permite. Cada rama solo puede estar en un worktree a la vez. Si necesitas ver el mismo código en dos lugares, crea una rama temporal con git worktree add -b copia-temporal ../copia main.
Borrar la carpeta con rm -rf en vez de git worktree remove. Git sigue creyendo que el worktree existe. Ejecuta git worktree prune para limpiar.
Olvidar hacer npm install o equivalente en el nuevo worktree. El worktree comparte el historial de Git, pero no las dependencias instaladas. Cada carpeta necesita su propio node_modules, venv, vendor, etc.
Crear worktrees dentro del repositorio principal. Pon los worktrees fuera de la carpeta del proyecto (usa ../nombre). Si los creas dentro, pueden generar confusión con archivos no rastreados.
No limpiar worktrees viejos. Con el tiempo se acumulan. Revisa periódicamente con git worktree list y elimina los que ya no uses.
Worktrees y editores de código
La mayoría de editores modernos manejan worktrees sin problemas:
- VS Code: abre cada worktree como una carpeta independiente. Las extensiones de Git funcionan normalmente.
- JetBrains (IntelliJ, WebStorm, PyCharm): abre la carpeta del worktree como un proyecto nuevo. Reconoce la rama automáticamente.
- Neovim/Vim: funciona directamente al navegar a la carpeta.
Un enfoque productivo: abre tu worktree principal en una ventana y el worktree secundario en otra. Dos ventanas, dos ramas, cero conflictos.
Worktree vs. stash vs. clon: resumen
| Worktree | Stash | Clon | |
|---|---|---|---|
| Ramas simultáneas | Sí | No | Sí |
| Comparte historial | Sí | Sí | No (copia independiente) |
| Duplica datos de Git | No | No | Sí |
Necesita npm install por separado |
Sí | No | Sí |
| Ideal para | Trabajo paralelo largo | Cambios rápidos | Entornos completamente aislados |
Idea clave
git worktree es una de esas herramientas que existen desde hace años pero que muy pocos desarrolladores conocen. Elimina por completo el patrón de stash-checkout-pop que rompe el flujo de trabajo, y lo reemplaza por algo más limpio: cada rama en su propia carpeta, sin interferencias. Si trabajas en equipos donde los cambios de contexto son frecuentes, aprenderlo te ahorra tiempo real todos los días.