Gestionar Ramas Git

Crea, cambia, sincroniza y limpia ramas siguiendo convenciones de nombres consistentes.

Cuándo Usar

• Al comenzar trabajo en una nueva funcionalidad o corrección de error
• Al cambiar entre tareas en distintas ramas
• Al mantener una rama de funcionalidad actualizada con main
• Al limpiar ramas después de fusionar pull requests
• Al listar e inspeccionar ramas

Entradas

• Requerido: Repositorio con al menos un commit
• Opcional: Convención de nombres de ramas (por defecto:

  tipo/descripcion

  )
• Opcional: Rama base para nuevas ramas (por defecto:

  main

  )
• Opcional: Nombre del remoto (por defecto:

  origin

  )

Procedimiento

Paso 1: Crear una Rama de Funcionalidad

Usa una convención de nombres consistente:

feature/

feature/add-weighted-mean

fix/

fix/null-pointer-in-parser

docs/

docs/update-api-reference

refactor/

refactor/extract-validation

chore/

chore/update-dependencies

test/

test/add-edge-case-coverage

# Create and switch to a new branch from main
git checkout -b feature/add-weighted-mean main

# Or using the newer switch command
git switch -c feature/add-weighted-mean main

Esperado: Se crea la nueva rama y se activa.

git branch

En caso de fallo: Si la rama base no existe localmente, primero haz fetch:

git fetch origin main && git checkout -b feature/name origin/main

Paso 2: Rastrear Ramas Remotas

Configura el rastreo al subir una nueva rama por primera vez:

# Push and set upstream tracking
git push -u origin feature/add-weighted-mean

# Check tracking relationship
git branch -vv

Para hacer checkout de una rama remota creada por otra persona:

git fetch origin
git checkout feature/their-branch
# Git auto-creates a local tracking branch

Esperado: La rama local rastrea la rama remota correspondiente.

git branch -vv

En caso de fallo: Si el rastreo automático falla, configúralo manualmente:

git branch --set-upstream-to=origin/feature/name feature/name

Paso 3: Cambiar de Rama de Forma Segura

Antes de cambiar, asegúrate de que el árbol de trabajo esté limpio:

# Check for uncommitted changes
git status

Si hay cambios, haz commit o guárdalos con stash:

# Option 1: Commit work in progress
git add <files>
git commit -m "wip: save progress on validation logic"

# Option 2: Stash changes temporarily
git stash push -m "validation work in progress"

# Switch branches
git checkout main

# Later, restore stashed changes
git checkout feature/add-weighted-mean
git stash pop

Listar y gestionar el stash:

# List all stashes
git stash list

# Apply a specific stash (without removing it)
git stash apply stash@{1}

# Drop a stash
git stash drop stash@{0}

Esperado: El cambio de rama tiene éxito. El árbol de trabajo refleja el estado de la rama destino. Los cambios guardados con stash son recuperables.

En caso de fallo: Si el cambio está bloqueado por cambios sin commit que serían sobreescritos, primero usa stash o haz commit.

git stash

git stash push -u

Paso 4: Sincronizar con el Upstream

Mantén tu rama de funcionalidad actualizada con la rama base:

# Fetch latest changes
git fetch origin

# Rebase onto latest main (preferred — keeps linear history)
git rebase origin/main

# Or merge main into your branch (creates merge commit)
git merge origin/main

Esperado: La rama incluye los últimos cambios de main. Sin conflictos, o conflictos resueltos (ver

resolve-git-conflicts

En caso de fallo: Si el rebase genera conflictos, resuelve cada uno y ejecuta

git rebase --continue

git rebase --abort

git merge origin/main

Paso 5: Limpiar Ramas Fusionadas

Después de que los pull requests sean fusionados, elimina las ramas obsoletas:

# Delete a local branch that has been merged
git branch -d feature/add-weighted-mean

# Delete a local branch (force, even if not merged)
git branch -D feature/abandoned-experiment

# Delete a remote branch
git push origin --delete feature/add-weighted-mean

# Prune remote-tracking references for deleted remote branches
git fetch --prune

Esperado: Las ramas fusionadas se eliminan local y remotamente.

git branch

En caso de fallo:

git branch -d

git branch -D

Paso 6: Listar e Inspeccionar Ramas

# List local branches
git branch

# List all branches (local and remote)
git branch -a

# List branches with last commit info
git branch -v

# List branches merged into main
git branch --merged main

# List branches NOT yet merged
git branch --no-merged main

# See which remote branch each local branch tracks
git branch -vv

Esperado: Vista clara de todas las ramas, su estado y las relaciones de rastreo.

En caso de fallo: Si las ramas remotas aparecen desactualizadas, ejecuta

git fetch --prune

Validación

• Los nombres de las ramas siguen la convención acordada
• Las ramas de funcionalidad se crean desde la rama base correcta
• Las ramas locales rastrean sus contrapartes remotas
• Las ramas fusionadas están limpias (local y remotamente)
• El árbol de trabajo está limpio antes de cambiar de rama
• Los cambios guardados con stash no quedan huérfanos

Errores Comunes

• Trabajar directamente en main: Crea siempre una rama de funcionalidad. Hacer commit directamente en main dificulta la creación de PRs y la colaboración.
• Olvidar hacer fetch antes de crear una rama: Crear una rama desde un main local desactualizado significa empezar atrasado. Siempre ejecuta

  git fetch origin

  primero.
• Ramas de larga duración: Las ramas de funcionalidad que viven semanas acumulan conflictos de fusión. Sincroniza con frecuencia y mantén las ramas de corta duración.
• Stashes huérfanos:

  git stash

  es almacenamiento temporal. No dependas de él para trabajo a largo plazo. Haz commit o crea una rama en su lugar.
• Eliminar trabajo no fusionado:

  git branch -D

  es destructivo. Verifica con

  git log branch-name

  antes de forzar la eliminación.
• No hacer prune: Las ramas remotas eliminadas en GitHub siguen apareciendo localmente hasta que ejecutas

  git fetch --prune

  .

Habilidades Relacionadas

• commit-changes

  - hacer commit del trabajo en las ramas

• create-pull-request

  - abrir PRs desde ramas de funcionalidad

• resolve-git-conflicts

  - resolver conflictos durante la sincronización

• configure-git-repository

  - configuración del repositorio y estrategia de ramas