---
version: 1.0.0
updated: 2026-03-11
tags: [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:

```bash
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:**

```bash
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:**

```bash
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:**

```bash
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:

```bash
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:

```bash
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

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

## Ejemplos

**Ejemplo 1: Limpiar una issue específica**

```bash
/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**

```bash
/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