Ejemplos de Git Worktree

Ejemplos prácticos y listos para copiar-pegar para el flujo de trabajo diario con worktrees: crear, cambiar de rama, fusionar, traer cambios y eliminar. Todos los comandos asumen una versión reciente de Git (2.23+) para que git switch funcione junto con el antiguo git checkout.

Receta

Tarjeta de referencia rápida -- lista para copiar-pegar.

# Crear + cambiar a una rama existente en un nuevo worktree
git worktree add ../feature-branch feature-branch
 
# Crear una nueva rama y cambiar a ella en un nuevo worktree
git worktree add ../new-feature -b new-feature
 
# HEAD desacoplado en un commit o tag específico
git worktree add ../hotfix abc1234
 
# Listar worktrees y la rama que cada uno tiene verificada
git worktree list
 
# Eliminar un worktree cuando termines
git worktree remove ../feature-branch
 
# Limpiar entradas obsoletas después de haber eliminado una carpeta manualmente
git worktree prune

Cuándo usarlo: Cualquier flujo de trabajo basado en worktrees -- desarrollo de features, aislamiento de hotfixes, revisión de PRs, comparación lado a lado.

Ejemplo Funcional

Ciclo de vida completo de una feature

# 1. Iniciar la feature en un nuevo worktree en una nueva rama
git worktree add ../my-feature -b my-feature
 
# 2. Moverte a él y trabaja normalmente
cd ../my-feature
# ...edita archivos, ejecuta pruebas, haz commit...
git add .
git commit -m "feat: scaffold my-feature"
 
# 3. Vuelve a main y fusiona
cd ../main-repo
git switch main
git pull origin main
git merge my-feature
 
# 4. Haz push y limpia
git push origin main
git worktree remove ../my-feature
git branch -d my-feature

Lo que esto demuestra:

• Los worktrees y las ramas comparten historial inmediatamente -- no se necesita un ciclo push/pull entre ellos.
• La fusión ocurre en el worktree destino (el que cuya rama recibirá los cambios).
• Eliminar un worktree deja la rama intacta; eliminar la rama es un paso separado e intencional.

Inmersión Profunda

1. Crear y cambiar de rama en worktrees

Los comandos principales -- comienza aquí.

# Crear un nuevo worktree y cambiar a una rama existente
git worktree add ../feature-branch feature-branch
 
# Crear una nueva rama Y cambiar a ella en un nuevo worktree
git worktree add ../new-feature -b new-feature
 
# Cambiar a un commit o tag específico (HEAD desacoplado)
git worktree add ../hotfix abc1234
 
# Alternativa moderna a git checkout (más segura para ramas)
git switch <branch>          # Dentro de un worktree
git switch -c <new-branch>   # Crear + cambiar

Consejo: Prefiere git switch sobre git checkout para operaciones de ramas (introducido en Git 2.23+). git checkout todavía funciona pero está sobrecargado con comportamiento de restauración de archivos, que es un arma de doble filo si escribes mal un nombre de rama.

2. Listar y gestionar ramas en worktrees

git branch -a                # Todas las ramas (locales + remotas)
git branch -v                # Con información del último commit
git worktree list            # Qué rama tiene verificada cada worktree
git worktree list --porcelain # Legible por máquinas para scripts

git worktree list es la respuesta a "espera, ¿dónde dejé ese hotfix?"

3. Fusionar ramas en worktrees (flujo de trabajo común)

La fusión ocurre en el worktree destino -- usualmente el que tiene main o una rama de lanzamiento verificada.

# Desde tu worktree principal:
cd ../main-project
git switch main              # o: git checkout main
git pull origin main         # Siempre actualiza primero
 
# Fusionar una rama de feature completada (desarrollada en otro worktree)
git merge feature-branch     # Fast-forward o crear un commit de fusión
 
# Fusionar con opciones
git merge --no-ff feature-branch     # Siempre crear un commit de fusión
git merge --squash feature-branch    # Aplastar cambios (luego hacer commit manualmente)
 
# Hacer rebase en su lugar, para un historial más limpio
git switch feature-branch    # Cambiar al worktree de la rama de feature primero
git rebase main
git switch main
git merge feature-branch     # Ahora un fast-forward limpio

Ejemplo de fusión entre worktrees:

1. Termina el trabajo y haz commit dentro de ../feature-worktree.
2. cd de vuelta al worktree principal.
3. git merge feature-branch -- el puntero de rama se actualizó automáticamente por el commit en el otro worktree.

Sin push, sin pull, sin viaje redondo remoto. La carpeta .git compartida hace que esto sea sin fricciones.

4. Traer cambios, pull y actualizar

git fetch origin             # Actualiza refs remotas -- visible desde todos los worktrees
git pull origin main         # Traer + fusionar en el worktree donde ejecutaste esto
 
# Actualizar la base de un worktree de feature
cd ../my-feature
git fetch origin
git rebase origin/main       # Reproducir tus commits de feature en la parte superior de main más reciente

Punto clave: git fetch actualiza el estado en la carpeta .git compartida, así que cada worktree ve las nuevas refs remotas inmediatamente. git pull solo afecta la rama verificada en el worktree donde lo ejecutaste.

5. Otros comandos útiles relacionados con checkout/merge

Cherry-pick de un commit desde otra rama o worktree:

git cherry-pick abc1234

Comparar ramas sin cambiar:

git diff main..feature-branch

Resolver conflictos durante una fusión (flujo estándar):

git status                   # Ver archivos en conflicto
# Editar cada archivo para resolver los marcadores
git add <file>
git merge --continue

Abortar una fusión:

git merge --abort

Para el manual completo de resolución de conflictos, consulta Checklist de Resolución de Conflictos de Fusión.

6. Ejemplo completo del ciclo de vida

# 1. Iniciar feature
git worktree add ../my-feature -b my-feature
 
# 2. Trabaja y haz commit en ese directorio...
cd ../my-feature
# ...código, pruebas, commit...
 
# 3. Fusionar de vuelta
cd ../main-repo
git switch main
git merge my-feature
 
# 4. Limpiar
git worktree remove ../my-feature
git branch -d my-feature     # Opcional: eliminar rama

7. Hotfixes que interrumpen el trabajo de feature en progreso

# Estás profundo en el trabajo de feature en ../my-feature, y la producción falla.
# No hagas stash. No cambies de rama. Solo crea un worktree de hotfix.
 
cd ~/projects/main-repo
git fetch origin
git worktree add ../hotfix -b hotfix/login-500 origin/main
 
cd ../hotfix
# ...depura, arregla, commit, push, abre PR...
git push -u origin hotfix/login-500
 
# Una vez que el PR se fusione, limpia
cd ~/projects/main-repo
git worktree remove ../hotfix
git branch -D hotfix/login-500   # Si la rama remota se eliminó al fusionar
 
# Vuelve a tu trabajo de feature, exactamente como lo dejaste
cd ../my-feature

8. Revisión de PR sin perturbar tu trabajo

# Un compañero de equipo hizo push a una rama que necesitas revisar
git fetch origin
git worktree add ../review-pr-482 origin/feature/teammate-thing
 
cd ../review-pr-482
npm install
npm run dev
# ...lee código, pruébalo, deja comentarios en el PR...
 
# Destrúyelo cuando termines
cd ../main-repo
git worktree remove ../review-pr-482

9. Comparación lado a lado

# Ejecuta dos implementaciones a la vez para una comparación real
git worktree add ../approach-a -b experiment/approach-a
git worktree add ../approach-b -b experiment/approach-b
 
# Dos ventanas de terminal, dos servidores de desarrollo en puertos diferentes, ambos editables.
# Cuando termines, mantén el ganador, elimina el perdedor.
git worktree remove ../approach-b
git branch -D experiment/approach-b

Consejos profesionales e inconvenientes

• Siempre haz commit o stash en los cambios antes de eliminar un worktree. Git se niega por defecto; usa --force solo cuando estés seguro.
• Ejecuta git worktree prune después de eliminar manualmente un directorio de worktree.
• git fetch una vez, ve actualizaciones en todas partes -- la carpeta .git compartida hace que las refs sean instantáneamente visibles en todos los worktrees.
• Para fusiones complejas, considera git mergetool -- funciona igual en cualquier worktree.
• Los submódulos necesitan git submodule update --init --recursive por worktree.

Gotchas

Cosas que te morderán. Cada gotcha incluye qué sale mal, por qué sucede y la solución.

• fatal: '<branch>' is already checked out at ... -- Intentaste añadir un worktree en una rama que está verificada en otro lugar. Solución: Trabaja en el worktree existente, o bifurca: git worktree add ../scratch -b scratch <branch>.

• Conflictos de rebase en un worktree de feature, luego olvidar actualizar el destino de fusión -- Hiciste rebase de feature sobre origin/main dentro de ../my-feature, pero en tu worktree principal olvidaste hacer git pull primero. Solución: Siempre git fetch + git pull en el worktree destino antes de fusionar.

• git checkout <branch> cambia los archivos en el worktree actual -- Querías añadir un worktree pero escribiste el comando antiguo. Solución: Usa git worktree add para crear un nuevo worktree; git switch/git checkout solo cambian el actual.

• Los stashes se aplican en worktrees y te sorprenden -- Hiciste stash en el worktree A, luego git stash pop en el worktree B aplica los archivos equivocados. Solución: Los stashes se comparten. Nómbralos (git stash push -m "feature X wip") y revisa con git stash list antes de hacer pop.

• Force-push de una rama desde un worktree rompe fusiones en otro -- El worktree A hace force-push de feature, el worktree B todavía tiene los commits antiguos verificados y un git pull desencadena un rechazo de fast-forward confuso. Solución: Coordina force-pushes; vuelve a ejecutar git fetch + git reset --hard origin/feature en el otro worktree si estás seguro.

• node_modules fuera de sincronización entre worktrees -- Actualizaste una dependencia en el worktree A; el worktree B todavía tiene la versión antigua instalada. Solución: Vuelve a ejecutar npm install (o tu equivalente) por worktree después de cambios de dependencias.

• Commit de fusión va a la rama equivocada -- Ejecutaste git merge feature desde un worktree que tenía develop verificado, no main. Solución: Ejecuta git branch --show-current antes de fusionar. Usa git reset --hard ORIG_HEAD para deshacer la fusión si no ha sido hecho push.

Alternativas

Otras formas de resolver el mismo problema -- y cuándo cada una es la mejor opción.

FAQs

git fetch origin
git worktree add ../review origin/feature/teammate-branch

cd ../my-feature
git fetch origin
git rebase origin/main

git cherry-pick <sha>

git diff main..feature-branch
git log main..feature-branch --oneline

git worktree prune

git worktree move ../old-path ../new-path

Relacionado

• Introducción a Git Worktrees -- El modelo mental y los comandos básicos
• Fusión & Rebase -- Combinando ramas en worktrees
• Checklist de Resolución de Conflictos de Fusión -- Cuando una fusión entre worktrees tiene conflictos
• Comandos Esenciales de Git -- Los comandos diarios en los que se construye cada flujo de trabajo de worktree