Files
repo_Claude/.claude/commands/workspace/cleanup-worktrees.md
T

5.7 KiB

version, updated, tags
version updated tags
1.0.0 2026-03-11
worktree
git
cleanup
automation

Command: cleanup-worktrees

Elimina worktrees y sus ramas locales asociadas después de haber sido mergeadas. Puede limpiar un worktree específico o todos los worktrees en worktrees/.

Flujo completo:

  1. Validar argumentos (issue number o --all)
  2. Listar worktrees a eliminar
  3. Para cada worktree:
    • Verificar que la rama fue mergeada
    • Eliminar worktree
    • Eliminar rama local
  4. Reportar limpieza completada

Inputs

Se necesita UNO de estos parámetros:

  • issue_number: Número de issue (NNNN) para limpiar solo ese worktree
  • --all: Limpiar todos los worktrees en worktrees/

Flujo obligatorio

1. Validar argumentos

Verificar que se proporcionó exactamente un argumento:

if [ $# -eq 0 ]; then
  echo "Error: Debes especificar un número de issue o --all"
  echo "Uso: /workspace:cleanup-worktrees <issue_number>"
  echo "     /workspace:cleanup-worktrees --all"
  exit 1
fi

if [ $# -gt 1 ]; then
  echo "Error: Demasiados argumentos"
  exit 1
fi

ARG=$1

2. Determinar worktrees a limpiar

Si es issue específica:

if [[ "$ARG" =~ ^[0-9]{4}$ ]]; then
  ISSUE_NUM=$ARG
  WORKTREE_PATH="worktrees/issue-$ISSUE_NUM"

  # Verificar que existe el worktree
  if [ ! -d "$WORKTREE_PATH" ]; then
    echo "Error: No existe el worktree $WORKTREE_PATH"
    exit 1
  fi

  WORKTREES=("$WORKTREE_PATH")
fi

Si es --all:

if [ "$ARG" = "--all" ]; then
  # Listar todos los worktrees en worktrees/
  if [ ! -d "worktrees" ]; then
    echo "No hay directorio worktrees/ para limpiar"
    exit 0
  fi

  # Obtener lista de directorios en worktrees/
  WORKTREES=($(find worktrees -maxdepth 1 -type d -name "issue-*" | sort))

  if [ ${#WORKTREES[@]} -eq 0 ]; then
    echo "No hay worktrees para limpiar"
    exit 0
  fi

  echo "Se encontraron ${#WORKTREES[@]} worktrees para limpiar"
fi

Si no es ninguno:

if [ -z "$WORKTREES" ]; then
  echo "Error: Argumento inválido '$ARG'"
  echo "Usa un número de issue (ej: 0003) o --all"
  exit 1
fi

3. Confirmar con el usuario

Mostrar lo que se va a eliminar:

echo "Se eliminarán los siguientes worktrees:"
for wt in "${WORKTREES[@]}"; do
  ISSUE_NUM=$(basename "$wt" | sed 's/issue-//')
  BRANCH="quick/fix-issue-$ISSUE_NUM"
  echo "  - $wt (rama: $BRANCH)"
done

echo ""
read -p "¿Continuar? (y/N): " CONFIRM

if [[ ! "$CONFIRM" =~ ^[Yy]$ ]]; then
  echo "Operación cancelada"
  exit 0
fi

4. Limpiar cada worktree

Para cada worktree en la lista:

for wt in "${WORKTREES[@]}"; do
  ISSUE_NUM=$(basename "$wt" | sed 's/issue-//')
  BRANCH="quick/fix-issue-$ISSUE_NUM"

  echo ""
  echo "Limpiando issue $ISSUE_NUM..."

  # Verificar que la rama fue mergeada (opcional, para seguridad)
  MERGED=$(git branch --merged main | grep -c "$BRANCH" || true)

  if [ "$MERGED" -eq 0 ]; then
    echo "⚠️  Advertencia: La rama $BRANCH NO ha sido mergeada a main"
    read -p "¿Eliminar de todas formas? (y/N): " FORCE

    if [[ ! "$FORCE" =~ ^[Yy]$ ]]; then
      echo "Saltando $wt"
      continue
    fi
  fi

  # Eliminar worktree
  echo "  → Eliminando worktree $wt..."
  git worktree remove "$wt" --force 2>/dev/null || {
    echo "  ⚠️  No se pudo eliminar worktree, puede que ya esté eliminado"
  }

  # Eliminar rama local
  echo "  → Eliminando rama $BRANCH..."
  git branch -D "$BRANCH" 2>/dev/null || {
    echo "  ⚠️  No se pudo eliminar rama, puede que ya esté eliminada"
  }

  echo "  ✓ Issue $ISSUE_NUM limpiada"
done

5. Reportar resultado

echo ""
echo "✓ Limpieza completada"
echo ""
echo "Worktrees restantes:"
git worktree list | grep -v "(bare)" || echo "  (ninguno)"

Ejemplos

Ejemplo 1: Limpiar una issue específica

/workspace:cleanup-worktrees 0003

Output:

Se eliminarán los siguientes worktrees:
  - worktrees/issue-0003 (rama: quick/fix-issue-0003)

¿Continuar? (y/N): y

Limpiando issue 0003...
  → Eliminando worktree worktrees/issue-0003...
  → Eliminando rama quick/fix-issue-0003...
  ✓ Issue 0003 limpiada

✓ Limpieza completada

Worktrees restantes:
  (ninguno)

Ejemplo 2: Limpiar todos los worktrees

/workspace:cleanup-worktrees --all

Output:

Se encontraron 3 worktrees para limpiar
Se eliminarán los siguientes worktrees:
  - worktrees/issue-0003 (rama: quick/fix-issue-0003)
  - worktrees/issue-0006 (rama: quick/fix-issue-0006)
  - worktrees/issue-0008 (rama: quick/fix-issue-0008)

¿Continuar? (y/N): y

Limpiando issue 0003...
  → Eliminando worktree worktrees/issue-0003...
  → Eliminando rama quick/fix-issue-0003...
  ✓ Issue 0003 limpiada

Limpiando issue 0006...
  → Eliminando worktree worktrees/issue-0006...
  → Eliminando rama quick/fix-issue-0006...
  ✓ Issue 0006 limpiada

Limpiando issue 0008...
  → Eliminando worktree worktrees/issue-0008...
  → Eliminando rama quick/fix-issue-0008...
  ✓ Issue 0008 limpiada

✓ Limpieza completada

Convenciones

  • Nomenclatura de worktrees: Siempre worktrees/issue-NNNN
  • Nomenclatura de ramas: Siempre quick/fix-issue-NNNN
  • Confirmación interactiva: Siempre pedir confirmación antes de eliminar
  • Verificación de merge: Advertir si la rama no fue mergeada

Reglas críticas

  • SIEMPRE verificar que la rama fue mergeada antes de eliminar (advertir si no)
  • NUNCA eliminar sin confirmación del usuario (a menos que se agregue flag --force en futuro)
  • SIEMPRE usar --force en git worktree remove para evitar errores por cambios sin commit
  • NUNCA fallar silenciosamente - reportar cada paso con claridad
  • SIEMPRE mostrar worktrees restantes al final para confirmar estado