git-worktree

Git Worktree

Ningún worktree nace sin que el usuario sepa dónde está, de dónde parte y cómo sale. Ningún worktree se elimina sin que el usuario lo pida.

Esta skill tiene precedencia sobre otras skills que crean worktree (ej.: superpowers:using-git-worktrees) en tres puntos: ubicación, nombre y aprobación. El resto del flujo de la otra skill sigue vigente.

Herramientas por agente

Acción	Claude Code	Codex
Crear	git worktree add + EnterWorktree(path: ...) para mover la sesión	git worktree add y trabajar con git -C/workdir en el worktree
Subagente aislado	Agent con isolation: "worktree" (crea en .claude/worktrees/)	no aplica
Salir	ExitWorktree(action: "keep")	volver al directorio original
Informe	pwsh -NoProfile -File "<carpeta de esta skill>/scripts/worktrees-report.ps1"	igual

<carpeta de esta skill> es el directorio donde está este SKILL.md. El script necesita PowerShell 7+ (pwsh).

1. Antes de crear

1. Verifica si ya estás en un worktree (git rev-parse --git-dir diferente de git rev-parse --git-common-dir, fuera de submódulo). Si lo estás, no crees otro sin que el usuario lo pida.
2. Ejecuta el informe en los repositorios involucrados y guarda el resultado para el paso 4:

   pwsh -NoProfile -File "<carpeta de esta skill>/scripts/worktrees-report.ps1" -Path "<repo1>;<repo2>"
   

3. Arma el plan con los estándares siguientes y presenta un bloque por worktree:

   Plan de worktree
   - Repositorio:     C:\repos\tienda
   - Rama base:       origin/main @ 3f2a9c1 (git fetch hecho ahora)
   - Rama nueva:      claude/feat-inicio-sesion-google
   - Nombre:          feat-inicio-sesion-google
   - Ubicación absoluta:  C:\repos\tienda\.worktrees\feat-inicio-sesion-google
   - Ubicación relativa:  .worktrees\feat-inicio-sesion-google
   - Cómo:            git -C "C:\repos\tienda" worktree add "C:\repos\tienda\.worktrees\feat-inicio-sesion-google" -b claude/feat-inicio-sesion-google origin/main
   - Eliminación:     git -C "C:\repos\tienda" worktree remove "C:\repos\tienda\.worktrees\feat-inicio-sesion-google"
                      git -C "C:\repos\tienda" branch -d claude/feat-inicio-sesion-google
   

   Si el repositorio tiene submódulos (.gitmodules), avisa en el plan que la eliminación necesitará --force y por qué.
4. Justo debajo, muestra la tabla del informe con los worktrees ya abiertos en esos repositorios (Worktree, Tamaño, Rama, Qué pierdo). Si no hay ninguno, dilo en una línea.
5. Espera el OK explícito del usuario. Solo entonces crea. En Claude Code, el hook del plugin pide una confirmación extra al ejecutar el comando. En Codex, la regla codex/rules/git-worktree.rules hace lo mismo para git worktree add.

Para varios subagentes en paralelo, presenta un único plan con todos los worktrees y pide un solo OK.

Estándares

• Ubicación: <raíz del repositorio>/.worktrees/<nombre>, en ambos agentes. La excepción es el subagente de Claude Code con isolation: "worktree", que siempre crea en .claude/worktrees/; en ese caso, informa esa ruta en el plan.
• Ignorar la carpeta sin commit: antes de crear, ejecuta git -C <repo> check-ignore -q .worktrees/x. Si la carpeta no está ignorada, añade .worktrees/ al archivo info/exclude del repositorio (ruta en git -C <repo> rev-parse --git-path info/exclude). Este archivo es local y no genera commit. Avisa que lo hiciste.
• Nombre: <tipo>-<descripcion-corta>, en kebab-case, con hasta 40 caracteres. Ejemplos: feat-inicio-sesion-google, fix-timeout-pago.
• Rama nueva: <agente>/<nombre>, es decir, claude/feat-inicio-sesion-google o codex/feat-inicio-sesion-google. Si el repositorio tiene su propia convención de ramas (hook, CONTRIBUTING, historial), sigue la del repositorio y di cuál es.
• Base: por defecto, la rama en la que el usuario está en el checkout principal. Usa origin/<rama predeterminada> si la tarea es independiente de ella. Ejecuta git fetch antes y muestra el hash corto de la base.

2. Informe de worktrees

Usa cuando el usuario pida listar o limpiar worktrees y en el paso 1.2 anterior.

pwsh -NoProfile -File "<carpeta de esta skill>/scripts/worktrees-report.ps1" [-Path "<raíz o repo>;..."] [-Json] [-SkipSize] [-Depth 6]

• Sin -Path, el script usa la variable GIT_WORKTREE_ROOTS o, si no está definida, el directorio actual. Si las instrucciones del usuario (CLAUDE.md, AGENTS.md) definen una carpeta raíz de repositorios, pasa esa carpeta.
• El script es de solo lectura. Encuentra repositorios, submódulos y worktrees sueltos fuera de la carpeta del repositorio.
• Usa -SkipSize si el usuario quiere rapidez. Usa -Json cuando necesites los detalles (commits adelante/atrás, estado en remoto, merge, fecha del último commit, veredicto y comandos de eliminación).

Muestra la tabla que imprime el script, exactamente con estas cuatro columnas y en este orden:

Columna	Contenido
Worktree	Ruta absoluta
Tamaño	Espacio en disco
Rama	Rama del worktree, o (detached @ <hash>)
Qué pierdo	Nada, o la lista de lo que desaparece al eliminar: archivos sin commit, commits que solo existen ahí, archivos ignorados por git (ej.: .env). Las carpetas de compilación (node_modules, bin, obj...) no cuentan

No añadas columnas. Los detalles van debajo de la tabla, solo cuando ayuden a decidir.

Lo que cuenta como pérdida:

• Archivos modificados o nuevos sin commit.
• Commits que no están en ningún remoto, ni en la rama actual, ni en la rama predeterminada.
• Archivos ignorados que no son de compilación.
• En submódulos inicializados: archivos sin commit y commits que solo existen en ellos.
• Un worktree bloqueado (git worktree lock) aparece con (bloqueado...) y no se elimina sin confirmación.
• Si la carpeta ya no existe, la columna dice Nada (la carpeta ya no existe...). Se resuelve con git worktree prune.
• Limitación: los merges por squash o rebase no se detectan, por lo que esos commits aparecen como pérdida. Si el usuario dice que el PR ya se fusionó, verifica en el remoto.

Cierra el informe con el espacio que se liberaría eliminando los que no pierden nada.

Comandos de eliminación

Cuando el usuario pida eliminar, o pida el comando, usa el campo ComandosEliminacion del -Json. Copia los comandos exactamente, en el orden y en un solo bloque. No escribas los comandos de memoria. El campo ya resuelve tres trampas:

1. Archivos ignorados: si hay archivos ignorados que se pierden (ej.: .env, .superpowers/), los primeros comandos los copian a ~/worktree-backup/<repo>/<worktree>. La copia tiene que ir antes de la eliminación: después de eliminar, no hay más que copiar.
2. Submódulos: si el worktree tiene submódulos inicializados, la eliminación viene con --force, porque git rechaza git worktree remove sin él. Antes de entregar ese comando, confirma en la columna "Qué pierdo" que los submódulos no pierden nada, o que el usuario aceptó la pérdida.
3. Rama: por último, git branch -d elimina la rama, que solo se elimina si ya está integrada.

Si tú mismo vas a ejecutar, ejecuta un comando por vez y detente en el primer error.

3. Al terminar la tarea

• Si el trabajo del worktree ya se integró (fusionado o enviado al remoto), propón la eliminación con los comandos listos.
• Si no se integró, di lo que falta: commit, push, PR.
• En Claude Code, sal con ExitWorktree(action: "keep") y solo elimina mediante git después del OK. ExitWorktree(action: "remove") solo funciona para worktrees que el propio EnterWorktree creó en la sesión.

Reglas que no cambian

• Nunca elimines worktree o rama sin que el usuario lo pida. Elimina uno a la vez y ejecuta el informe de nuevo al final.
• Nunca uses git branch -D o ExitWorktree(discard_changes: true) sin confirmación explícita para ese worktree. git worktree remove --force solo aplica cuando el worktree tiene submódulos (ver "Comandos de eliminación") y el usuario ya vio lo que se pierde.
• Nunca crees un worktree sin haber presentado el plan y recibido el OK.