git worktree: cómo trabajar en varias ramas a la vez

Qué hace git worktree

git worktree conecta a un mismo repositorio varios directorios de trabajo. En la carpeta principal tienes abierta la rama de tu feature y en la de al lado, main para un hotfix urgente, y ambas existen a la vez. Los objetos, los commits y las ramas son compartidos: un commit hecho en una carpeta se ve al instante desde la otra, sin push ni fetch.

Sin worktree, cambiar de contexto es así: git stash, git switch main, la corrección, git switch de vuelta, git stash pop. Si el proyecto tiene un build largo o un node_modules pesado, cada cambio de rama además invalida las cachés. La otra opción es volver a clonar el repositorio, pero entonces tienes dos copias independientes del historial que hay que sincronizar a través del servidor remoto.

Worktree ofrece lo mejor de ambos enfoques: carpetas separadas, pero una sola base .git. Es posible porque una rama en Git no es más que un puntero a un commit, no una copia de los archivos, y nada impide que distintas copias de trabajo miren a punteros distintos.

Cómo crear una copia de trabajo adicional

La forma básica del comando es git worktree add <ruta> [<rama>]. Veamos las variantes principales.

Abrir una rama existente

cd ~/projects/shop
git worktree add ../shop-main main
Preparing worktree (checking out 'main')
HEAD is now at 3f2c1ab Actualizar el README

Junto al proyecto aparecerá la carpeta shop-main con la rama main. Entra en ella con un cd normal y trabaja como en cualquier repositorio.

Crear una rama nueva junto con la copia de trabajo

git worktree add -b hotfix/payment-timeout ../shop-hotfix main

La opción -b crea la rama hotfix/payment-timeout a partir de main y la abre en la carpeta nueva. La opción -B hace lo mismo, pero si la rama ya existe, la restablece al commit indicado: úsala con cuidado.

Forma abreviada

git worktree add ../experiment

Si no indicas la rama, Git creará una rama nueva con el nombre del último componente de la ruta (aquí experiment) a partir del HEAD actual. Si ya existe una rama con ese nombre, abrirá esa.

Copia de trabajo sin rama

git worktree add --detach ../shop-v1.4 v1.4.0

El modo detached HEAD es práctico para compilar o probar una release antigua por su etiqueta sin crear ramas innecesarias.

Una rama del servidor remoto

git fetch origin
git worktree add ../review-auth feature/auth

Si no existe la rama local feature/auth pero hay exactamente una remota origin/feature/auth, Git creará una rama local con seguimiento, como con git switch feature/auth. Es una forma cómoda de revisar el pull request de otra persona sin tocar tu trabajo.

Cómo ver y eliminar las copias de trabajo

git worktree list
/home/anna/projects/shop            a1b2c3d [feature/cart]
/home/anna/projects/shop-hotfix     7e8f9a0 [hotfix/payment-timeout]
/home/anna/projects/shop-v1.4       5d6e7f8 (detached HEAD)

La primera línea es la copia de trabajo principal (main worktree); las demás son las vinculadas (linked). Para scripts existe una salida legible por máquina: git worktree list --porcelain.

Cuando el hotfix ya está fusionado, elimina la copia de trabajo:

git worktree remove ../shop-hotfix
git branch -d hotfix/payment-timeout

git worktree remove borra la carpeta y los registros internos. Si en la copia hay cambios sin commit o archivos sin seguimiento, el comando se negará; añade --force solo si estás seguro de que no los necesitas. Ojo: la rama en sí no se borra; se elimina aparte.

Si borraste la carpeta a mano

Borrar la carpeta con el explorador de archivos o con rm -rf deja en .git/worktrees un registro «huérfano», y la rama sigue considerándose ocupada. Limpia esos registros:

git worktree prune --verbose

Git también lo hace periódicamente durante la recolección de basura, pero no hace falta esperar.

Cómo funciona por dentro

En una copia de trabajo vinculada, en lugar de la carpeta .git hay un archivo .git con una sola línea:

gitdir: /home/anna/projects/shop/.git/worktrees/shop-hotfix

En esa carpeta interna se guardan los datos propios de la copia de trabajo: su HEAD, su índice (staging area), sus estados de merge y rebase. Todo lo demás es compartido: objetos, ramas, etiquetas, repositorios remotos, configuración y hooks.

De la tabla se deduce un detalle poco obvio: git stash list muestra las mismas entradas en cualquier copia. Incluso es práctico: puedes guardar cambios en una carpeta y recuperarlos en otra.

La limitación principal: una rama, una copia de trabajo

No se puede abrir la misma rama en dos copias de trabajo. Si lo intentas, Git responderá con un error de este estilo:

git worktree add ../shop-copy feature/cart
fatal: 'feature/cart' is already used by worktree at '/home/anna/projects/shop'

(en versiones antiguas de Git el texto dice «is already checked out at»). La limitación evita que un commit en una carpeta cambie en silencio la rama bajo los pies de la otra. Soluciones: crear una rama nueva desde el mismo commit (-b), abrir la copia en modo --detach o, si es imprescindible, usar --force asumiendo las consecuencias.

Por la misma razón, en la carpeta principal no podrás ejecutar git switch main mientras main esté abierta en otra copia de trabajo.

Casos prácticos

Un hotfix urgente en mitad de una feature

git worktree add -b hotfix/null-price ../shop-hotfix main
cd ../shop-hotfix
# corregimos y probamos
git commit -am "Corregir el fallo con precio vacío"
git push -u origin hotfix/null-price
cd ../shop
git worktree remove ../shop-hotfix

Tu feature a medias se ha quedado como estaba, no has tenido que guardar nada en stash y el IDE con el proyecto abierto ni siquiera ha notado el cambio.

Revisar un pull request ejecutando el código

Una copia aparte para la revisión permite compilar y ejecutar la rama de otra persona, pasar los tests y, a la vez, seguir con tu trabajo en otra ventana del editor.

Comparar el comportamiento de dos versiones

Dos copias con etiquetas distintas pueden ejecutarse en paralelo en puertos diferentes para comparar, por ejemplo, el tiempo de respuesta de la API antes y después de una optimización.

Tests y builds largos

Lanza la batería completa de tests en una copia y sigue escribiendo código en otra: el build no se romperá porque estés cambiando archivos.

Varios agentes de IA trabajando en paralelo

Si varios agentes o procesos trabajan en distintas tareas, conviene dar a cada uno su propia copia de trabajo en su propia rama: no se estorban y los resultados llegan directamente al repositorio común.

Cómo organizar las carpetas si usas worktree a diario

Si necesitas copias de trabajo todos los días, decide una estructura; si no, los directorios vecinos se convertirán pronto en un caos. Un esquema popular es una carpeta padre del proyecto con un repositorio bare dentro y una carpeta por rama:

git clone --bare git@example.com:team/shop.git ~/projects/shop/.bare
cd ~/projects/shop
echo "gitdir: ./.bare" > .git
git config remote.origin.fetch "+refs/heads/*:refs/remotes/origin/*"
git fetch origin

git worktree add main
git worktree add -b feature/cart feature-cart main

La línea con remote.origin.fetch hace falta porque un clon bare no configura por defecto el seguimiento de las ramas remotas. El resultado: en ~/projects/shop están las carpetas main y feature-cart, cada una con su rama, y ninguna es «más principal» que la otra.

Otro buen hábito es llamar a la carpeta igual que la rama (cambiando la barra por un guion). Así, por la salida de git worktree list y por la ruta en el terminal siempre sabrás dónde estás. Y por último, elimina la copia en cuanto se fusione la rama: las copias antiguas ocupan espacio y mantienen las ramas «ocupadas».

Errores habituales y trampas

• Las dependencias y el build no se comparten. Cada copia es una carpeta aparte, así que node_modules, el entorno virtual de Python, .env y los artefactos de compilación habrá que volver a crearlos. Los archivos sin seguimiento no se trasladan a la copia nueva.
• Una copia de trabajo dentro de la carpeta principal. El comando git worktree add ./hotfix creará la carpeta dentro del proyecto, y la copia principal la verá como archivos sin seguimiento. Mantén las copias al lado (../) o en un directorio aparte, o añade la ruta a .gitignore.
• Mover la carpeta a mano. El vínculo se romperá. Muévela con git worktree move ../old ../new y, si ya la moviste, ejecuta git worktree repair en la carpeta nueva.
• Una copia en un disco extraíble desaparece. Para que prune no elimine el registro de una copia en un disco desconectado, bloquéala: git worktree lock --reason "disco externo" ../shop-usb.
• Submódulos. El soporte de submodules en copias de trabajo es limitado; tras crear la copia, ejecuta git submodule update --init y comprueba el resultado.

Chuleta de git worktree

git worktree, stash o un segundo clon

Stash sigue siendo la mejor opción para interrupciones cortas de un par de minutos. Para todo lo que dure más, o cuando necesitas tener abiertas dos versiones, worktree es más cómodo.

Conclusión

git worktree es una forma sencilla de trabajar con varias ramas a la vez: add crea la carpeta, list las muestra, remove y prune las eliminan. El historial es común, pero HEAD, el índice y los archivos son propios de cada copia; una misma rama no puede estar abierta en dos copias. Cómo funcionan las ramas y por qué cambiar entre ellas es tan ligero lo vemos en detalle, con práctica, en el curso de Git.