worktree-manager

Gestiona git worktrees siguiendo la estrategia de carpeta .worktrees/ dentro del repositorio.

Triggers

Frases que activan el skill
“crear worktree”
“nuevo branch en paralelo”
“trabajar en otra feature”
“limpiar worktrees”
“listar worktrees”

¿Qué son los Worktrees?

Los worktrees permiten tener múltiples branches checked out simultáneamente en carpetas separadas, sin necesidad de hacer stash o commit de cambios incompletos.

Ventajas:

  • Cambiar de contexto sin perder trabajo
  • Trabajar en múltiples features en paralelo
  • Revisar código de otros branches sin cambiar tu working directory

Estructura 

~/Projects/mi-proyecto/
├── .worktrees/                     # ignorado por .gitignore
│   ├── feature-auth/               # worktree para branch feature-auth
│   └── bugfix-login/               # worktree para branch bugfix-login
├── src/                            # archivos del repo (main)
└── .gitignore                      # incluye .worktrees/

Comandos disponibles

Setup inicial (una vez por proyecto) 

# Agregar .worktrees/ a .gitignore
echo ".worktrees/" >> .gitignore

# Crear carpeta
mkdir -p .worktrees

# Commit del cambio
git add .gitignore
git commit -m "chore: ignore worktrees folder"

Crear worktree 

git worktree add .worktrees/feature-nueva -b feature-nueva

Listar worktrees 

git worktree list

Eliminar worktree (después de merge) 

# Desde el directorio raíz
git worktree remove .worktrees/feature-auth

# Eliminar branch remoto
git push origin --delete feature-auth

# Eliminar branch local
git branch -d feature-auth

Podar referencias huérfanas 

git worktree prune

Flujo de trabajo completo

Nueva Feature 

# 1. Asegurar que estamos en main actualizado
git checkout main
git pull origin main

# 2. Crear worktree
git worktree add .worktrees/feature-auth -b feature-auth

# 3. Trabajar en el worktree
cd .worktrees/feature-auth
# ... hacer cambios ...
git add .
git commit -m "feat: add authentication"
git push -u origin feature-auth

# 4. Crear PR
gh pr create --title "feat: add authentication" --body "..."

# 5. Después del merge, limpiar
cd ../..
git worktree remove .worktrees/feature-auth
git push origin --delete feature-auth

Principios clave

Principio Descripción
Temporales Worktrees no son casas permanentes, se eliminan después del merge
Main limpio El repo principal siempre está en main/master
Nombres descriptivos Carpeta = nombre del branch
Cleanup obligatorio Siempre limpiar después del merge del PR

Troubleshooting

Error: “worktree already exists” 

# Verificar worktrees existentes
git worktree list
ls -la .worktrees/

Error: “branch already exists” 

# Opción 1: Usar branch existente (sin -b)
git worktree add .worktrees/feature-x feature-x

# Opción 2: Eliminar branch viejo
git branch -D feature-x
git worktree add .worktrees/feature-x -b feature-x

Error: “is already checked out” 

# Ver dónde está el branch
git worktree list

# Remover el worktree anterior
git worktree remove .worktrees/branch-name

Worktrees huérfanos 

# Limpiar referencias a worktrees eliminados manualmente
git worktree prune

Herramientas disponibles

  • Bash - Ejecutar comandos git
  • Read - Leer archivos
  • Write - Crear archivos de configuración