using-git-worktrees

Descripción general

¿Qué es using-git-worktrees?

using-git-worktrees es una skill de flujo de trabajo del repositorio obra/superpowers que te guía para crear worktrees de Git aislados para el desarrollo de funcionalidades. Estandariza cómo y dónde se crean los worktrees, para que puedas trabajar con varias ramas a la vez sin tener que cambiar constantemente de rama en un único directorio de trabajo.

En lugar de decidir manualmente dónde colocar los worktrees o arriesgarte a crear directorios sin seguimiento o sin ignorar, esta skill codifica un proceso claro de selección y verificación de directorios. El objetivo es conseguir un aislamiento fiable para el trabajo de implementación, manteniendo limpio el árbol principal de tu proyecto.

¿Para quién es esta skill?

Esta skill está pensada para desarrolladores que:

• Trabajan en varias funcionalidades o correcciones en paralelo
• Quieren una convención repetible de Git worktree entre proyectos
• Necesitan la seguridad de que los directorios de worktree se colocan correctamente y no contaminarán los commits
• Usan Git en la línea de comandos y se sienten cómodos ejecutando comandos de shell sencillos

Encaja especialmente bien en equipos que buscan un flujo de trabajo Git documentado, consistente y una forma más segura de levantar entornos de funcionalidad temporales o de larga duración.

¿Qué problemas resuelve using-git-worktrees?

using-git-worktrees te ayuda a evitar problemas habituales al trabajar con múltiples ramas:

• Sobrecarga al cambiar de rama: Trabaja con varias ramas al mismo tiempo sin tener que hacer stash y checkout continuamente.
• Raíces de proyecto desordenadas: Evita dispersar directorios ad hoc y carpetas de worktree en ubicaciones aleatorias.
• Commits accidentales de carpetas de worktree: El flujo hace hincapié en verificar que los directorios locales de worktree estén ignorados antes de crearlos.
• Convenciones inconsistentes entre máquinas: Al comprobar los directorios existentes y las preferencias opcionales en CLAUDE.md, la skill te orienta hacia un layout estándar por proyecto.

Si usas Git worktrees con frecuencia o quieres empezar a usarlos de forma segura, esta skill te ofrece un procedimiento ligero y con opinión.

¿Cuándo es buena idea usar using-git-worktrees?

Deberías usar using-git-worktrees cuando:

• Estás a punto de empezar trabajo de funcionalidad que necesita aislarse de tu espacio de trabajo actual.
• Vas a implementar algo a partir de un diseño o plan existente y quieres un worktree limpio para ejecutar esa implementación.
• Tu repositorio ya utiliza directorios .worktrees o worktrees y quieres seguir respetando esa convención.

Puede ser menos útil si:

• Solo trabajas en una rama a la vez y no necesitas múltiples copias de trabajo.
• Ya tienes una herramienta interna estricta y automatizada que gestiona los worktrees de otra manera.

En el resto de casos, adoptar el flujo de using-git-worktrees puede hacer tu flujo de trabajo con Git más predecible y seguro.

Cómo usarla

Instalación y configuración

Para añadir la skill using-git-worktrees a tu entorno, instálala desde el repositorio obra/superpowers:

npx skills add https://github.com/obra/superpowers --skill using-git-worktrees

Después de la instalación:

1. Abre el archivo skills/using-git-worktrees/SKILL.md en el checkout del repositorio.
2. Léelo de principio a fin una vez para entender los pasos de selección de directorios y verificación de seguridad.
3. Asegúrate de que estás trabajando dentro de un repositorio Git en el que te sientas cómodo creando directorios adicionales de worktree.

No necesitas dependencias extra aparte de Git y un shell que pueda ejecutar los comandos que se muestran en la descripción de la skill.

Flujo principal: iniciar trabajo de funcionalidad aislado

Cuando empieces trabajo en una nueva funcionalidad y quieras un espacio de trabajo aislado, sigue el flujo de alto nivel definido por using-git-worktrees:

1. Anuncia el flujo de trabajo (para ti y para cualquier asistente o herramienta):

   "I'm using the using-git-worktrees skill to set up an isolated workspace."

2. Determina el directorio del worktree usando el proceso de selección de directorios (ver la sección siguiente). Esto evita que los worktrees acaben dispersos en rutas arbitrarias.

3. Ejecuta la verificación de seguridad apropiada para el tipo de directorio elegido (local al proyecto vs. global). Este paso es esencial para evitar commits accidentales de carpetas de worktree.

4. Crea el worktree de Git para la rama que necesites. Por ejemplo:

   git worktree add <path-to-worktree> <branch-name>
   

5. Cambia al nuevo worktree y realiza ahí tu trabajo de implementación, dejando tu copia de trabajo original limpia y disponible para revisiones de código, correcciones rápidas u otras tareas.

Repite este flujo siempre que empieces una nueva funcionalidad, spike o experimento que no deba interferir con tu directorio de trabajo actual.

Proceso de selección de directorios

using-git-worktrees define un orden estructurado de selección de directorios para que siempre sepas dónde deben vivir los worktrees y no tengas que volver a decidirlo cada vez.

1. Prioriza directorios de worktree existentes

Desde la raíz de tu repositorio, comprueba si hay directorios preferentes para worktrees en este orden de prioridad:

ls -d .worktrees 2>/dev/null     # Preferred (hidden)
ls -d worktrees 2>/dev/null      # Alternative

• Si existe .worktrees, úsalo.
• Si no existe .worktrees pero sí worktrees, usa worktrees.
• Si no existe ninguno, pasa al siguiente paso.

Esta regla hace que tu flujo de trabajo sea consistente con elecciones anteriores en el mismo proyecto.

2. Revisa CLAUDE.md para ver las preferencias del proyecto

Si no hay un directorio de worktree estándar, busca una preferencia documentada en CLAUDE.md en la raíz del proyecto:

grep -i "worktree.*director" CLAUDE.md 2>/dev/null

Si CLAUDE.md especifica una convención de directorio para worktrees, úsala sin hacer más preguntas. Esto permite que el proyecto documente de forma centralizada su layout preferido de worktrees.

3. Pregunta y elige una nueva ubicación cuando no haya preferencia

Si no existe ningún directorio y no hay preferencia documentada en CLAUDE.md, elige explícitamente dónde deberían vivir los nuevos worktrees. La skill sugiere plantearte (a ti o a tu equipo) una elección clara:

No worktree directory found. Where should I create worktrees?

1. .worktrees/ (project-local, hidden)
2. ~/.config/superpowers/worktrees/<project-name>/ (global location)

Which would you prefer?

• Opción 1: .worktrees/ mantiene los worktrees junto al proyecto, ocultos por defecto y fáciles de descubrir en el repo.
• Opción 2: ~/.config/superpowers/worktrees/<project-name>/ centraliza los worktrees por proyecto fuera de la raíz del repo, lo que puede ser útil si quieres que tu directorio de trabajo de Git se mantenga visualmente minimalista.

Una vez elijas una opción, sigue usando esa ubicación para el mismo proyecto para evitar la fragmentación.

Verificación de seguridad antes de crear un worktree

La skill using-git-worktrees enfatiza las comprobaciones de seguridad, especialmente cuando se usan directorios locales al proyecto que viven dentro del repositorio Git.

Verificar que los directorios locales al proyecto estén ignorados

Para directorios locales al proyecto como .worktrees o worktrees, verifica que Git los esté ignorando antes de crear worktrees dentro de ellos. La skill señala esto como una condición MUST.

Como mínimo, deberías:

• Confirmar que .worktrees o worktrees aparece en un archivo de ignore relevante (.gitignore, .git/info/exclude o archivos de ignore globales), y
• Usar git check-ignore para asegurarte de que Git realmente ignora el directorio en tu configuración actual.

Un patrón de comprobación típico es ejecutar git check-ignore sobre la ruta del directorio y confirmar que Git lo trata como ignorado, respetando las configuraciones de ignore locales, globales y de sistema.

Si el directorio no está ignorado:

• Añádelo a un archivo de ignore adecuado, haz commit de la regla de ignore si debe vivir en el repositorio, y
• Vuelve a ejecutar la comprobación antes de crear worktrees en esa ubicación.

Esto reduce el riesgo de que tu infraestructura de worktrees acabe en staging o en un commit por accidente.

Usar ubicaciones globales de forma segura

Si eliges la opción de directorio global (por ejemplo, bajo ~/.config/superpowers/worktrees/), los directorios viven fuera del repositorio y no están trackeados por Git. En ese caso, el requisito de ignore es menos crítico, pero aun así deberías asegurarte de que:

• La ruta sea estable entre máquinas (o esté documentada para tus compañeros de equipo).
• Tienes suficiente espacio en disco para múltiples worktrees completos.

Aplicar estas verificaciones de forma consistente mantiene tu historial de Git centrado en cambios de código, no en artefactos de herramientas.

Adaptar la skill a tu flujo de trabajo

La skill using-git-worktrees es deliberadamente ligera y centrada en el repositorio. Para integrarla en tu flujo de trabajo más amplio:

• Documenta tu elección final de directorio de worktrees en la documentación de contribución u onboarding del proyecto.
• Considera añadir una breve sección a CLAUDE.md describiendo cómo usa tu equipo los Git worktrees.
• Envuelve los pasos de selección de directorio y verificación en tus propios scripts de shell si quieres tener una configuración de un solo comando, manteniendo las reglas originales como fuente de verdad.

La skill está pensada como una implementación de referencia clara que puedes seguir tal cual o adaptar con cuidado para que encaje en tu entorno.

FAQ

¿Cuál es la principal ventaja de using-git-worktrees frente a los checkouts normales de Git?

using-git-worktrees facilita trabajar con varias ramas en paralelo creando directorios de trabajo adicionales (worktrees) que comparten el mismo historial de Git. En lugar de hacer checkout y stash repetidamente en un único directorio, mantienes cada funcionalidad o fix en su propio espacio de trabajo aislado, guiado por un proceso consistente de selección de directorios y seguridad.

¿Cómo instalo la skill using-git-worktrees?

Instala la skill desde el repositorio obra/superpowers usando:

npx skills add https://github.com/obra/superpowers --skill using-git-worktrees

Después de instalarla, abre skills/using-git-worktrees/SKILL.md en tu checkout local para seguir el flujo de trabajo detallado.

¿Tengo que cambiar mi flujo de trabajo actual de Git para usar esta skill?

No tienes que rehacer por completo tu flujo de trabajo. using-git-worktrees se centra en cómo inicias y gestionas espacios de trabajo aislados. Puedes seguir haciendo commit, rebase y push como siempre; la skill principalmente estandariza dónde y cómo creas worktrees y se asegura de que se ubiquen de forma segura.

¿Puedo usar using-git-worktrees en cualquier repositorio Git?

Sí, siempre que el repositorio sea compatible con Git worktrees en general. La skill se basa en comandos estándar de Git y utilidades de shell. Para obtener los mejores resultados, ejecuta las comprobaciones de directorios desde la raíz del repositorio y sigue las recomendaciones de ignore para cualquier directorio de worktree local al proyecto.

¿Qué pasa si mi proyecto ya tiene una convención distinta para los worktrees?

Si tu proyecto ya utiliza .worktrees, worktrees o una convención documentada en CLAUDE.md, using-git-worktrees tomará esa preferencia de forma natural gracias a sus reglas de selección de directorios. Si tu convención es totalmente distinta, aún puedes adaptar los principios (elección clara de directorio y comprobaciones de seguridad) apuntándolos a tu layout de directorios existente.

¿Es using-git-worktrees adecuada para proyectos grandes o de larga duración?

Sí. La skill es especialmente útil para proyectos grandes donde son habituales varias ramas de larga duración. Su selección estructurada de directorios y el énfasis en las reglas de ignore ayudan a mantener tu repositorio organizado con el tiempo, incluso cuando acumulas muchos worktrees para trabajos en curso.

¿Cuándo debería evitar usar using-git-worktrees?

Puede que no necesites esta skill si rara vez trabajas en más de una rama a la vez, o si tu equipo ya utiliza otra herramienta dedicada que gestiona los worktrees y aplica sus propias convenciones de directorios. En estos casos, la estructura adicional de using-git-worktrees puede no aportar suficiente valor como para justificar cambiar tus hábitos.

¿Dónde puedo ver la definición original de esta skill?

La definición autorizada de using-git-worktrees está en el archivo SKILL.md dentro del directorio skills/using-git-worktrees del repositorio obra/superpowers en GitHub. Consulta ese archivo para obtener la descripción de comportamiento más precisa y actualizada.