repo_Claude/.claude/commands/git/branch.md

version, updated, tags

version	updated	tags
2.0.0	2026-03-11	git workflow trunk-based

Command: git-branch

Crea una rama de trabajo. Nunca trabajar directamente en master.

Para el usuario

Cuándo usar este comando

Usar siempre antes de empezar cualquier trabajo. Dataforge sigue trunk-based development estricto: todo el trabajo se hace en ramas temporales que se integran rápidamente a master.

Sintaxis

/git:branch issue <NNNN> <slug>
/git:branch quick <slug>

Ejemplos

Ejemplo 1: Rama para issue existente

/git:branch issue 0013 hot-reload

Crea rama issue/0013-hot-reload para implementar el issue 0013.

Ejemplo 2: Rama para cambio rápido

/git:branch quick fix-typo-readme

Crea rama quick/fix-typo-readme para fix pequeño sin issue asociado.

Para Claude

Precondiciones

Verificar antes de ejecutar:

• Repositorio es un repo git válido
• Branch master existe
• No hay cambios sin commitear (working tree limpio)

Inputs

Preguntar al usuario si el cambio está asociado a un issue o no.

Si es un issue:

• issue_number: número de 4 dígitos (e.g. 0020)
• slug: nombre corto separado por guiones (e.g. hot-reload)

Si es un cambio rápido (sin issue):

• slug: nombre corto descriptivo separado por guiones (e.g. fix-typo-readme)

Flujo obligatorio

1. Verificar estado actual del repositorio

{{include: git-verify-clean}}

git branch --show-current
git status --short

Si no estamos en master:

git checkout master

Si hay cambios sin commitear: ✗ Error: Working tree no está limpio

⚠ Avisar al usuario y STOP hasta resolver:

Hay cambios sin commitear. Opciones:

1. Commitear cambios primero:
   git add .
   git commit -m "mensaje"

2. Hacer stash:
   git stash

3. Descartar cambios (⚠ peligroso):
   git reset --hard

2. Actualizar master desde remoto

{{include: git-update-master}}

git pull --rebase

3. Crear la rama según tipo

Para issues:

git checkout -b issue/<issue_number>-<slug>

Ejemplo: git checkout -b issue/0013-hot-reload

Para cambios rápidos:

git checkout -b quick/<slug>

Ejemplo: git checkout -b quick/fix-typo-readme

4. Verificar creación de rama

git branch --show-current

Debe mostrar el nombre de la nueva rama.

Verificación final

Informar al usuario:

✓ Rama `<nombre-rama>` creada desde master actualizado

Puedes empezar a trabajar.

Cuando termines:
  /git:push

Convenciones

• Formato de rama issue: issue/<NNNN>-<slug> (siempre 4 dígitos)
• Formato de rama quick: quick/<slug> (sin número)
• Ramas cortas: idealmente horas, no días
• Una rama por issue: no mezclar issues en la misma rama
• Nunca pushear la rama al remoto: el push se hace desde master después del merge
• No rebase interactivo: si los commits son limpios desde el inicio, no reescribir historia
• No commits WIP: cada commit en la rama debe ser atómico y con mensaje real

Features multi-issue

Para features que no caben en una sola rama, usar sub-issues con sufijo letra:

issue/0015a-telegram-types
issue/0015b-telegram-client
issue/0015c-telegram-listener
issue/0015d-telegram-enable

Cada sub-rama sigue el mismo flujo: crear → implementar → merge --no-ff → delete. El código parcial se protege con feature flags en dev/feature_flags.json (no con commits WIP).

Troubleshooting

Error: "fatal: not a git repository"

Causa: El directorio actual no es un repositorio git.

Solución:

git init
# O navegar al directorio correcto
cd /ruta/al/repo

Error: "Your branch is behind 'origin/master'"

Causa: Master local está desactualizado respecto al remoto.

Solución:

git pull --rebase

Error: "fatal: A branch named 'issue/0013-hot-reload' already exists"

Causa: La rama ya existe localmente.

Solución:

1. Verificar si tiene cambios importantes:

git log issue/0013-hot-reload

2. Si no tiene cambios importantes, borrar:

git branch -D issue/0013-hot-reload

3. Si tiene cambios importantes, usar otro nombre o recuperar esos cambios primero.

Advertencia: "You have unstaged changes"

Causa: Hay archivos modificados sin stagear.

Solución:

1. Ver cambios:

git status

2. Decidir qué hacer:
   • Commitear: git add . && git commit -m "mensaje"
   • Descartar: git restore <archivo>
   • Stash: git stash

Reglas críticas

• NUNCA trabajar directamente en master sin rama temporal
• SIEMPRE verificar que el working tree esté limpio antes de crear rama
• SIEMPRE actualizar master desde remoto antes de crear rama
• NO pushear las ramas temporales al remoto (se integran via merge a master)
• NO usar underscores en nombres de rama, solo guiones
• NO crear ramas de larga duración (máximo 1-2 días, idealmente horas)