git branch

Ramas y merges

Listar, crear o eliminar ramas

El comando 'git branch' te permite crear, listar, renombrar y borrar ramas. No sirve para cambiar de rama: para eso usa 'git switch' o 'git checkout'. En Git las ramas son punteros ligeros a commits, así que crear ramas y cambiar entre ellas es rapidísimo. Sin argumentos, git branch lista las ramas existentes y resalta la actual. Con un nombre de rama, crea una rama nueva que apunta al HEAD actual. Las ramas son esenciales para el desarrollo en paralelo: permiten avanzar en varias funcionalidades o arreglos a la vez sin que se estorben.

Sinopsis

git branch [--list] [-a | -r] [-v [--abbrev=<n> | --no-abbrev]] [--merged | --no-merged] [<pattern>...]
git branch <branch-name> [<start-point>]
git branch (-d | -D) [-r] <branch-name>...
git branch (-m | -M) [<old-branch>] <new-branch>
git branch (-c | -C) [<old-branch>] <new-branch>
git branch [--set-upstream-to=<upstream> | -u <upstream>] [<branch-name>]
[ ] opcional| o<arg> valor a sustituir... repetible--flag opción

Opciones

Haz clic en una opción para desplegarla

Principiante (7)

Listar las ramas que coinciden con uno o varios patrones comodín de la shell. Sin patrón, lista todas las ramas locales. La opción --list es obligatoria al filtrar; si no, Git interpreta el patrón como el nombre de una rama nueva que crear.

RecomendadoNecesario para filtrar por patrón; sin él, un patrón crea una rama

Ejemplo

git branch --list "feature-*"

Listar tanto las ramas de seguimiento remoto como las locales. Muestra todas las ramas que existen en local y todas las ramas remotas que conoce tu repositorio.

RecomendadoVer juntas las ramas locales y de seguimiento remoto tras un fetch

Ejemplo

git branch -a

Listar solo las ramas de seguimiento remoto. Son referencias locales (refs/remotes/...) que representan el estado de las ramas de los repositorios remotos en el momento del último fetch.

Cuando haga faltaLista solo las ramas de seguimiento remoto; ejecuta antes git fetch

Ejemplo

git branch -r

Borrar una rama. La rama debe estar totalmente integrada en su upstream, o en HEAD si no se fijó upstream. Es un borrado seguro que te protege de perder trabajo.

RecomendadoLimpieza segura: se niega si la rama tiene trabajo sin fusionar

Ejemplo

git branch -d feature-complete

Mover/renombrar una rama junto con su configuración y su reflog. Si estás en la rama, puedes omitir el nombre antiguo.

RecomendadoRenombra una rama y conserva su reflog; falla sin riesgo si el nombre ya existe

Ejemplo

git branch -m old-name new-name

Mostrar el hash y el asunto de cada rama, y cuánto va por delante o por detrás de su upstream. Usa -vv para mostrar también el nombre de la rama upstream (y la ruta de un worktree vinculado).

Recomendado-vv muestra de un vistazo el upstream y los recuentos por delante/por detrás

Ejemplo

git branch -v

Mostrar el nombre de la rama actual. Con HEAD separado (detached) no se muestra nada. Una salida limpia, perfecta para scripts y automatización.

Cuando haga faltaImprime solo el nombre de la rama; útil en scripts y prompts

Ejemplo

git branch --show-current

Intermedio (10)

Forzar el borrado de una rama aunque tenga cambios sin integrar. Atajo de --delete --force. Úsalo con cuidado: algunos commits pueden quedar inalcanzables.

No recomendadoBorra trabajo sin fusionar: solo cuando estés seguro de que los commits se pueden tirar

Ejemplo

git branch -D abandoned-feature

Forzar el renombrado de una rama, sobrescribiendo el destino si ya existe. Atajo de --move --force. La rama sobrescrita se pierde.

No recomendadoSobrescribe sin avisar una rama existente; usa -m salvo que quieras sustituirla a propósito

Ejemplo

git branch -M main master

Copiar una rama junto con su configuración y su reflog. Crea una rama nueva en el mismo commit que la de origen. La rama original se conserva (a diferencia de --move).

Cuando haga faltaDuplica una rama con su configuración; poco habitual en el día a día

Ejemplo

git branch -c feature feature-backup

Listar las ramas cuya punta es alcanzable desde el commit indicado (HEAD si no se indica). Estas ramas ya están totalmente incorporadas y se pueden borrar con seguridad con -d.

RecomendadoMuestra las ramas totalmente fusionadas que se pueden borrar con seguridad

Ejemplo

git branch --merged main

Listar solo las ramas cuya punta NO es alcanzable desde el commit indicado (HEAD si no se indica). Estas ramas contienen trabajo aún sin integrar y requieren atención antes de borrarse.

Cuando haga faltaMuestra las ramas con trabajo aún sin integrar

Ejemplo

git branch --no-merged

Configurar la relación de seguimiento entre una rama local y una rama remota. Así git pull/push funcionan sin indicar el remoto ni el nombre de la rama.

RecomendadoEnlaza una rama con su remoto para que pull y push funcionen sin más

Ejemplo

git branch -u origin/main

Quitar la información de seguimiento del upstream de una rama. Después, git pull y git push necesitarán que indiques explícitamente el remoto y la rama.

Cuando haga faltaElimina el enlace de seguimiento, p. ej. cuando la rama remota ya no existe

Ejemplo

git branch --unset-upstream

Crear una rama local nueva que sigue a una rama remota. La rama nueva tendrá el upstream configurado automáticamente para git pull/push.

Cuando haga faltaDefine el upstream al crearla; ya es lo predeterminado a partir de una rama remota

Ejemplo

git branch --track feature origin/feature

Listar solo las ramas cuyo commit de la punta desciende del commit indicado (lo contiene). Útil para saber qué ramas tienen un arreglo o una funcionalidad concreta. Si no se indica commit, se usa HEAD.

Cuando haga faltaEncuentra qué ramas incluyen ya una corrección o un commit

Ejemplo

git branch --contains a1b2c3d

Ordenar las ramas según la clave indicada. Usa el prefijo - para orden descendente. Claves habituales: committerdate, authordate, refname.

Cuando haga falta--sort=-committerdate muestra primero las ramas con actividad reciente

Ejemplo

git branch --sort=-committerdate

Elegir la opción adecuada

Ver ramas

Distintas formas de listar e inspeccionar ramas

ComandoMuestra localesMuestra remotasInformación extraCaso de uso
git branchSíNoRama actual marcada con *Vistazo rápido a las ramas locales
git branch -rNoSíReferencias de seguimiento remotoVer qué hay en el servidor
git branch -aSíSíTodas las referenciasVisión completa de todas las ramas
git branch -vSíNoÚltimo commit de cada ramaVer la actividad de las ramas de un vistazo
git branch -vvSíNoUpstream + adelanto/retrasoComprobar la sincronización con el remoto
git branch --show-currentSolo la actualNoSolo el nombreScripts, prompts de la shell

Borrar ramas

Borrado seguro frente a borrado forzado: conoce la diferencia

ComandoExige estar integradaPuede perder trabajoCuándo usarla
-d (--delete)SíNoTras integrar un PR, limpieza rutinaria
-D (--delete --force)NoSíAbandonar un trabajo experimental

Renombrar y copiar ramas

Opciones para reorganizar los nombres de tus ramas

ComandoSobrescribe la existenteConserva la originalUso típico
-m (--move)No (falla)NoRenombrar: feature → feature-v2
-M (--move --force)SíNoReemplazar un nombre de rama existente
-c (--copy)No (falla)SíDuplicar una rama para experimentar
-C (--copy --force)SíSíCopiar, sobrescribiendo si existe

Filtrar ramas según si están integradas

Encontrar ramas listas para borrar o aún en curso

ComandoMuestraPropósitoPaso siguiente habitual
--mergedRamas integradas en HEADEncontrar candidatas a limpiezagit branch -d <branch>
--merged mainRamas integradas en mainEncontrar ramas que se pueden borrar con seguridadBorrar en bloque las ramas integradas
--no-mergedRamas NO integradasEncontrar trabajo en cursoRevisar antes de una release
--contains <commit>Ramas que contienen un commitSeguir adónde fue un arregloVerificar el despliegue de un hotfix

Seguimiento del upstream

Configurar la relación entre ramas locales y remotas

ComandoAcciónEfectoCuándo usarla
-u origin/mainFijar el upstreamgit push/pull funcionan sin argumentosTras crear una rama local
--track origin/featureCrear + fijar el upstreamNueva rama local que sigue a una remotaEmpezar a trabajar en una rama remota
--unset-upstreamQuitar el upstreamDesconectarse del remotoDejar de seguir una rama remota borrada

Ejemplos de flujos de trabajo

1
git branch feature-login

Crear una rama nueva para la funcionalidad

2
git switch feature-login

Cambiarse a la rama nueva

3
(make changes and commits)

Trabajar en la funcionalidad con varios commits

4
git switch main && git merge feature-login

Integrar la funcionalidad terminada en main

5
git branch -d feature-login

Borrar la rama de la funcionalidad tras el merge

1
git branch --merged

Listar las ramas ya integradas

2
git branch -d branch-name

Borrar con seguridad las ramas integradas una a una

3
git fetch --prune

Quitar referencias de seguimiento remoto obsoletas

4
git branch -r

Comprobar que las ramas remotas están limpias

1
git fetch origin

Traer la información más reciente de las ramas remotas

2
git branch -r

Listar las ramas remotas disponibles

3
git branch --track feature origin/feature

Crear una rama local que sigue a la remota

4
git switch feature

Cambiarse a la nueva rama de seguimiento

1
git branch -m old-name new-name

Renombrar la rama local

2
git push origin -u new-name

Subir el nombre nuevo de la rama al remoto

3
git push origin --delete old-name

Borrar el nombre antiguo de la rama del remoto

1
git log --oneline -1

Obtener el hash del commit que buscas

2
git branch --contains <commit-hash>

Encontrar ramas locales con este commit

3
git branch -r --contains <commit-hash>

Encontrar ramas remotas con este commit

Solución de problemas

No se puede borrar la rama: no está totalmente integrada

Causa: La rama tiene commits que no están integrados en su upstream (o en HEAD si no tiene upstream)

Integra primero la rama, o usa -D para forzar el borrado si estás seguro de querer descartar ese trabajo

git branch -D branch-name

No se puede borrar la rama actual

Causa: Estás intentando borrar la rama en la que estás

Cámbiate primero a otra rama y luego borra la rama que quieras

git switch main && git branch -d old-branch

Ese nombre de rama ya existe

Causa: Estás intentando crear una rama con un nombre que ya existe

Elige otro nombre, borra primero la rama existente o usa -f para moverla a un nuevo punto de partida

git branch -f existing-name <start-point>

No hay upstream configurado para el push

Causa: La rama local no tiene relación de seguimiento con ninguna rama remota

Configura la relación de seguimiento con el upstream

git push -u origin branch-name

La rama remota no aparece en git branch -r

Causa: El repositorio local no tiene la información más reciente de las ramas remotas

Haz fetch desde el remoto para actualizar tus ramas de seguimiento remoto

git fetch origin

HEAD separado (detached) tras un checkout

Causa: Hiciste checkout de un commit directamente en lugar de una rama

Crea una rama nueva en el commit actual o vuelve a una rama existente

git switch -c new-branch-name

La rama sigue al remoto equivocado

Causa: El upstream está configurado para seguir una rama remota incorrecta

Vuelve a fijar el seguimiento del upstream en la rama remota correcta

git branch -u origin/correct-branch

No se ven todas las ramas

Causa: Por defecto solo se muestran las ramas locales

Usa la opción -a para mostrar tanto las ramas locales como las de seguimiento remoto

git branch -a

Consejos y trampas

Buenas prácticas

  • ✓Usa nombres de rama descriptivos que indiquen su propósito: feature/user-auth, bugfix/login-error, hotfix/security-patch
  • ✓Borra las ramas tras el merge para mantener limpio el repositorio; usa 'git branch --merged' para encontrar las que se pueden borrar sin riesgo
  • ✓Crea siempre las ramas de funcionalidad desde una rama main al día para reducir los conflictos de merge
  • ✓Usa 'git branch -vv' para ver las relaciones de seguimiento y cuánto vas por delante o por detrás
  • ✓Configura el seguimiento al crear ramas con 'git push -u origin branch-name' para facilitar push y pull
  • ✓Evita trabajar directamente en main/master: crea siempre una rama para tus cambios
  • ✓Usa 'git branch --no-merged' para encontrar las ramas con trabajo aún en curso
  • ✓Sincroniza a menudo las ramas remotas con 'git fetch --prune' para quitar referencias obsoletas
  • ✓Plantéate usar 'git switch' en lugar de 'git checkout' para que la intención quede más clara al cambiar de rama
  • ✓Usa '--sort=-committerdate' para ver primero las ramas con actividad más reciente
  • ✓Antes de borrar una rama con -D, comprueba con 'git log branch-name' que ya no la necesitas
  • ✓Escribe los nombres de rama en minúsculas y con guiones, por coherencia y compatibilidad

Errores comunes

  • ✗Esperar que 'git branch <name>' te cambie a la rama nueva. Solo la crea: usa 'git switch <name>' o 'git checkout -b <name>' para crearla y cambiarte a ella.
  • ✗Intentar borrar la rama actual. Primero tienes que cambiarte a otra rama antes de borrar aquella en la que estás.
  • ✗Usar -d en ramas sin integrar y perder trabajo. La opción -d te protege: si de verdad quieres borrar trabajo sin integrar, usa -D.
  • ✗Olvidar subir las ramas nuevas al remoto. Las ramas locales no se comparten hasta que haces 'git push -u origin <branch>'.
  • ✗No limpiar las ramas viejas. Usa a menudo 'git branch --merged' para encontrar y borrar las ramas ya integradas.

Preguntas frecuentes

A:

'git branch <name>' solo crea una rama nueva, pero no te cambia a ella. 'git checkout -b <name>' crea una rama nueva Y te cambia a ella en un solo comando. El equivalente moderno es 'git switch -c <name>'.

A:

Usa 'git branch -m old-name new-name' para renombrar una rama. Si estás en la rama que quieres renombrar, basta con 'git branch -m new-name'. Para las ramas remotas tendrás que subir el nombre nuevo y borrar el antiguo.

A:

-d es un borrado seguro que solo funciona si la rama está totalmente integrada en su upstream (o en HEAD si no hay upstream). -D es un borrado forzado que elimina la rama sin mirar si está integrada. Usa -D solo cuando estés seguro de querer descartar commits sin integrar.

A:

Usa 'git push origin --delete branch-name' o la sintaxis corta 'git push origin :branch-name'. Esto elimina la rama del repositorio remoto.

A:

Las ramas de seguimiento remoto (como origin/main) son referencias locales que siguen el estado de las ramas de los repositorios remotos. Se actualizan al hacer fetch o pull y te muestran adónde apuntan las ramas remotas.

A:

Usa 'git branch --show-current' para ver solo el nombre, o 'git branch' para ver todas las ramas con la actual marcada con *. 'git status' también muestra la rama actual.

A:

Git no permite borrar la rama en la que estás. Cámbiate primero a otra rama con 'git switch other-branch' y luego borra la rama que quieras.

A:

Usa 'git branch branch-name commit-hash' para crear una rama que empiece en cualquier commit. Como punto de partida puedes usar un hash de commit, una etiqueta u otro nombre de rama.

A:

La rama upstream (o de seguimiento) es la rama remota a la que tu rama local sube y de la que trae cambios por defecto. Fíjala con 'git branch -u origin/branch-name' o 'git push -u origin branch-name'.

A:

Usa 'git branch --sort=-committerdate' para listar primero las ramas con los commits más recientes. Añade -v para ver también el hash y el mensaje del commit.