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

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

### Ejemplos

**Ejemplo 1: Rama para issue existente**
```bash
/git:branch issue 0013 hot-reload
```

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

**Ejemplo 2: Rama para cambio rápido**
```bash
/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}}

```bash
git branch --show-current
git status --short
```

**Si no estamos en master:**
```bash
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}}

```bash
git pull --rebase
```

#### 3. Crear la rama según tipo

**Para issues:**
```bash
git checkout -b issue/<issue_number>-<slug>
```

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

**Para cambios rápidos:**
```bash
git checkout -b quick/<slug>
```

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

#### 4. Verificar creación de rama

```bash
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:**
```bash
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:**
```bash
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:
```bash
git log issue/0013-hot-reload
```

2. Si no tiene cambios importantes, borrar:
```bash
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:
```bash
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)