Un nombre de rama equivocado no es para siempre
Las ramas son una de las herramientas más útiles de Git. Permiten trabajar en una funcionalidad nueva, corregir un error o experimentar con una idea sin tocar el código estable del proyecto. Cada rama tiene un nombre, y ese nombre importa más de lo que parece: aparece en las solicitudes de integración, en los registros de los sistemas de integración continua, en los tableros de tareas y en la conversación diaria del equipo.
Por eso, tarde o temprano, todo desarrollador se encuentra con la necesidad de cambiar el nombre de una rama. A veces es una simple errata, como feature/pago-con-tarjta. Otras veces la tarea cambió de alcance y el nombre original ya no describe el trabajo, o el equipo adoptó una convención nueva, como prefijar las ramas con el número de la incidencia. Y en muchos repositorios antiguos sigue pendiente un cambio más delicado: pasar la rama principal de master a main.
Renombrar una rama en tu equipo es inmediato. Renombrarla en el servidor remoto, ya sea GitHub, GitLab, Bitbucket o un servidor propio, requiere algunos pasos adicionales y un poco de cuidado si otras personas están trabajando sobre ella.
En esta guía veremos cómo renombrar ramas locales, cómo trasladar ese cambio al repositorio remoto, cómo mantener correctamente el seguimiento entre ambas, qué hacer con la rama principal y cómo resolver los errores más habituales. Todos los comandos funcionan con las versiones actuales de Git, cuya rama estable más reciente es la 2.55.
Antes de empezar: comprobar las ramas existentes
Antes de renombrar nada, conviene tener una imagen clara de qué ramas existen y en cuál estás trabajando. El comando git branch lista las ramas locales y marca con un asterisco la actual:
git branch
* feature/pago-con-tarjta
main
Para ver también las ramas remotas que tu repositorio conoce, añade la opción -a:
git branch -a
* feature/pago-con-tarjta
main
remotes/origin/feature/pago-con-tarjta
remotes/origin/main
Y para saber qué rama remota sigue cada rama local, la opción -vv es la más informativa:
git branch -vv
* feature/pago-con-tarjta b76f45f [origin/feature/pago-con-tarjta] Añade validación de tarjeta
main 428cfcd [origin/main] Versión inicial
El texto entre corchetes es la rama upstream, la rama remota con la que se compara la local al ejecutar git status, git pull o git push sin argumentos. Este detalle será importante más adelante.
Si trabajas en equipo, es buena idea ejecutar antes git fetch --prune para sincronizar la lista de ramas remotas y eliminar referencias a ramas que ya no existen en el servidor:
git fetch --prune
Renombrar la rama en la que estás trabajando
El caso más sencillo es renombrar una rama local mientras estás situado en ella. El comando es git branch con la opción -m, de move, seguido del nuevo nombre:
git branch -m feature/pago-con-tarjeta
No hay mensaje de confirmación; si el comando no devuelve nada, ha funcionado. Puedes comprobarlo con git branch:
* feature/pago-con-tarjeta
main
Internamente, Git no copia ni mueve ningún archivo ni ningún commit. Una rama no es más que un puntero a un commit, almacenado como una referencia con un nombre. Renombrarla consiste en cambiar el nombre de esa referencia, así que la operación es instantánea independientemente del tamaño del repositorio. Git también renombra el registro de movimientos de la rama, conocido como reflog, y actualiza la configuración asociada a ella.
Si todavía no estás en la rama que quieres renombrar, puedes cambiarte a ella con git switch, el comando recomendado desde hace años para cambiar de rama, en lugar del polivalente git checkout:
git switch feature/pago-con-tarjta
git branch -m feature/pago-con-tarjeta
git checkout sigue funcionando, pero mezcla dos responsabilidades, cambiar de rama y restaurar archivos, lo que ha causado muchas confusiones. git switch y git restore separan ambas tareas y son más seguros para quien está empezando.
Renombrar otra rama sin cambiarte a ella
No es necesario estar en una rama para renombrarla. Si pasas a git branch -m dos argumentos, el primero es el nombre actual y el segundo el nuevo:
git branch -m feature/pago-con-tarjta feature/pago-con-tarjeta
Esto es útil cuando estás en medio de otro trabajo con cambios sin confirmar y no quieres cambiar de rama solo para corregir un nombre.
Si el nombre nuevo ya está ocupado por otra rama, Git se niega a sobrescribirla:
git branch -m main
fatal: a branch named 'main' already exists
La variante en mayúscula, -M, fuerza el cambio y sobrescribe la rama existente. Úsala solo si estás completamente seguro de que la rama que vas a reemplazar ya no contiene trabajo que necesites, porque sus commits dejarán de estar referenciados por esa rama. Aun así, podrían recuperarse durante un tiempo a través del reflog.
git branch -M rama-temporal feature/pago-con-tarjeta
Un caso especial donde -M es útil y seguro es el cambio de mayúsculas y minúsculas en sistemas de archivos que no distinguen entre ellas, como los habituales en Windows y macOS. Pasar de Feature/Login a feature/login puede fallar con -m porque, para el sistema de archivos, ambos nombres son el mismo.
Por qué renombrar en local no cambia el remoto
Un error muy común es pensar que, tras renombrar una rama local, el cambio llegará al servidor con el siguiente git push. No es así. Git no tiene un comando para renombrar ramas en el repositorio remoto, y la rama remota sigue existiendo con el nombre antiguo.
Además, la rama local renombrada conserva su upstream antiguo, como puedes ver con git status:
git status -sb
## feature/pago-con-tarjeta...origin/feature/pago-con-tarjta
La rama local se llama ya con el nombre correcto, pero sigue apuntando a la rama remota con la errata. Si en este punto ejecutas git push, según tu configuración, Git rechazará el envío porque los nombres no coinciden o, peor aún, actualizará la rama remota antigua.
Para trasladar el cambio al servidor hay que hacer dos cosas: crear en el remoto una rama con el nuevo nombre y eliminar la antigua. El orden en el que se hagan es flexible, aunque crear primero la nueva tiene una ventaja que veremos enseguida.
Renombrar la rama en el repositorio remoto
El proceso completo consiste en publicar la rama con su nuevo nombre, configurar de nuevo el upstream para que apunte a ella y, por último, borrar la rama antigua del servidor.
Primero, publica la rama renombrada y establece el seguimiento con la opción -u, abreviatura de --set-upstream:
git push -u origin feature/pago-con-tarjeta
To github.com:tostadero/tienda.git
* [new branch] feature/pago-con-tarjeta -> feature/pago-con-tarjeta
branch 'feature/pago-con-tarjeta' set up to track 'origin/feature/pago-con-tarjeta'.
Después, elimina del servidor la rama con el nombre antiguo:
git push origin --delete feature/pago-con-tarjta
To github.com:tostadero/tienda.git
- [deleted] feature/pago-con-tarjta
Comprueba que todo ha quedado como esperabas:
git branch -vv
* feature/pago-con-tarjeta b76f45f [origin/feature/pago-con-tarjeta] Añade validación de tarjeta
main 428cfcd [origin/main] Versión inicial
Publicar primero la rama nueva y borrar después la antigua garantiza que en ningún momento el trabajo exista solo en tu equipo. Si algo falla entre ambos pasos, como una pérdida de conexión, el servidor tendrá temporalmente las dos ramas, pero no habrás perdido nada.
También existe una sintaxis más antigua para borrar ramas remotas, que consiste en empujar una referencia vacía con dos puntos delante del nombre. Hace exactamente lo mismo, pero es menos legible:
git push origin :feature/pago-con-tarjta
Incluso es posible publicar la rama con el nuevo nombre y eliminar la rama remota antigua en un solo comando, combinando ambas referencias:
git push origin :feature/pago-con-tarjta feature/pago-con-tarjeta
git branch --set-upstream-to=origin/feature/pago-con-tarjeta
En este caso, el upstream se configura aparte con --set-upstream-to, o su forma abreviada -u aplicada a git branch.
Resumen de comandos en un único flujo
Para tenerlo a mano, este es el flujo completo de renombrado de una rama que ya existe en el remoto:
# 1. Sincronizar y situarse en la rama
git fetch --prune
git switch feature/pago-con-tarjta
# 2. Renombrar en local
git branch -m feature/pago-con-tarjeta
# 3. Publicar con el nuevo nombre y configurar el seguimiento
git push -u origin feature/pago-con-tarjeta
# 4. Eliminar el nombre antiguo del remoto
git push origin --delete feature/pago-con-tarjta
# 5. Verificar
git branch -vv
Si haces esto con frecuencia, puedes crear un alias de Git que encapsule el proceso. Este ejemplo define el comando git renombrar, que recibe el nombre nuevo y renombra la rama actual en local y en origin:
git config --global alias.renombrar '!f() { \
viejo=$(git branch --show-current); \
git branch -m "$1" && \
git push -u origin "$1" && \
git push origin --delete "$viejo"; \
}; f'
git renombrar feature/pago-con-tarjeta
El operador && asegura que cada paso solo se ejecuta si el anterior ha tenido éxito, de modo que nunca se borrará la rama antigua si la nueva no se ha publicado.
Qué ocurre con las solicitudes de integración abiertas
Si la rama tenía abierta una pull request en GitHub o una merge request en GitLab, borrar la rama remota y crear otra con nombre distinto tiene efectos que conviene conocer. En la mayoría de plataformas, eliminar la rama de origen de una pull request abierta la cierra automáticamente, y crear la rama nueva no la reabre: tendrías que abrir una nueva solicitud y perderías el hilo de revisión en la interfaz.
Por eso, cuando la rama ya tiene una solicitud abierta, es mejor renombrarla desde la interfaz web de la plataforma. GitHub permite renombrar ramas desde la página de ramas del repositorio y, al hacerlo, actualiza automáticamente las pull requests abiertas, las reglas de protección asociadas y redirige el nombre antiguo. GitLab también permite cambiar la rama de origen o destino desde la configuración de la merge request.
Con la interfaz de línea de comandos de GitHub, gh, puedes hacer lo mismo desde la terminal mediante su API:
gh api repos/tostadero/tienda/branches/feature/pago-con-tarjta/rename \
-f new_name=feature/pago-con-tarjeta
Después de renombrar en el servidor, solo queda sincronizar tu copia local, como se explica en la siguiente sección.
Actualizar las copias locales del resto del equipo
Cuando la rama renombrada es compartida, el cambio en el servidor no se propaga automáticamente a los equipos de tus compañeros. Cada uno tiene su propia rama local con el nombre antiguo, que sigue apuntando a una rama remota que ya no existe. Es necesario que los colaboradores actualicen sus copias locales con unos pocos comandos:
# Descargar los cambios y eliminar referencias remotas obsoletas
git fetch origin --prune
# Renombrar la rama local
git branch -m feature/pago-con-tarjta feature/pago-con-tarjeta
# Apuntar al nuevo upstream
git branch -u origin/feature/pago-con-tarjeta feature/pago-con-tarjeta
Si un compañero ejecuta git status sin haber hecho estos pasos, verá que su upstream ha desaparecido:
## feature/pago-con-tarjta...origin/feature/pago-con-tarjta [gone]
La marca [gone] indica que la rama remota que se estaba siguiendo ya no existe. Es una señal clara de que alguien la ha renombrado o eliminado.
Antes de renombrar una rama compartida, avisa al equipo, preferiblemente en el canal donde se coordina el trabajo, e indica los comandos que deben ejecutar. Si alguien envía cambios a la rama antigua con un git push después de que la hayas borrado, la volverá a crear en el servidor y el equipo terminará con dos ramas divergentes.
Cambiar la rama principal de master a main
Un caso especialmente frecuente es renombrar la rama principal del repositorio. Desde 2020, GitHub, GitLab y Bitbucket usan main como nombre por defecto para los repositorios nuevos, y muchos equipos han migrado sus repositorios antiguos desde master.
El proceso es el mismo que para cualquier rama, con un paso adicional: cambiar la rama por defecto en la plataforma de alojamiento antes de borrar la antigua, porque la mayoría de servicios no permiten eliminar la rama por defecto.
# 1. Renombrar en local y publicar
git switch master
git branch -m master main
git push -u origin main
# 2. Cambiar la rama por defecto en la plataforma
# (en GitHub: Settings > General > Default branch)
gh repo edit tostadero/tienda --default-branch main
# 3. Eliminar la rama antigua del remoto
git push origin --delete master
También hay que actualizar la referencia simbólica HEAD del remoto en tu copia local, para que Git sepa cuál es la rama principal del servidor:
git remote set-head origin --auto
Y cada colaborador deberá ejecutar en su equipo:
git fetch origin --prune
git branch -m master main
git branch -u origin/main main
git remote set-head origin --auto
Como ocurre con cualquier rama, GitHub ofrece renombrar la rama por defecto directamente desde la interfaz, lo que actualiza automáticamente las reglas de protección, las pull requests abiertas y los borradores de publicaciones, y redirige las URL que contienen el nombre antiguo. Es la opción más cómoda para repositorios con mucha actividad.
No olvides revisar todo lo que dependa del nombre de la rama principal: flujos de GitHub Actions o GitLab CI con filtros como branches: [master], configuraciones de despliegue, enlaces en la documentación, insignias del archivo README y scripts internos.
# .github/workflows/ci.yml
on:
push:
branches: [main]
pull_request:
branches: [main]
Para que tus repositorios nuevos empiecen ya con main, configura el nombre por defecto de forma global:
git config --global init.defaultBranch main
Si no estableces esta opción, las versiones recientes de Git siguen creando master por defecto y muestran un aviso que sugiere configurar init.defaultBranch.
Convenciones para nombrar ramas
Muchas veces la necesidad de renombrar nace de no haber seguido una convención desde el principio. Algunas pautas que evitan problemas:
- Usa minúsculas y guiones en lugar de espacios o guiones bajos:
feature/pago-con-tarjeta. - Agrupa por tipo con un prefijo:
feature/,fix/,hotfix/,docs/,chore/. - Incluye el identificador de la incidencia si tu equipo usa un gestor de tareas:
fix/TIEN-482-redondeo-iva. - Mantén los nombres cortos y descriptivos.
- Evita tildes y caracteres especiales, que pueden dar problemas en algunas terminales y herramientas.
Git impone sus propias restricciones sobre los nombres de las referencias. No se permiten espacios, dos puntos seguidos, los caracteres ~, ^, :, ?, * o [, ni nombres que terminen en .lock o en barra. Puedes comprobar si un nombre es válido con git check-ref-format:
git check-ref-format --branch "feature/pago con tarjeta"
fatal: 'feature/pago con tarjeta' is not a valid branch name
Hay otra limitación menos evidente: Git almacena las ramas con barras como directorios, de modo que no pueden coexistir una rama llamada feature y otra llamada feature/login. Intentar renombrar una rama a un nombre que entre en conflicto de esta forma produce un error.
Errores frecuentes y cómo resolverlos
Al renombrar ramas aparecen siempre los mismos mensajes de error, y casi todos tienen una solución sencilla.
Si intentas renombrar una rama que no existe, normalmente por una errata en el nombre:
fatal: no branch named 'feature/pago-con-tarjtaa'
Lista las ramas con git branch y copia el nombre exacto. El autocompletado de la terminal ayuda mucho a evitar este error.
Si intentas publicar una rama con un nombre que no existe en local:
error: src refspec feature/pago-con-tarjeta does not match any
error: failed to push some refs to 'github.com:tostadero/tienda.git'
Comprueba con git branch que el renombrado local se ha hecho correctamente y que no hay diferencias de mayúsculas.
Si intentas borrar la rama por defecto del remoto:
! [remote rejected] master (refusing to delete the current branch: refs/heads/master)
Cambia primero la rama por defecto en la configuración del repositorio en la plataforma y vuelve a intentarlo.
Si la rama está protegida, la plataforma rechazará tanto el borrado como, en algunos casos, la creación de ramas con ciertos patrones:
! [remote rejected] release/2026-10 (protected branch hook declined)
Revisa las reglas de protección de ramas o los conjuntos de reglas del repositorio, o pide a un administrador que haga el cambio.
Si tras renombrar, git push sin argumentos falla porque el upstream no coincide:
fatal: The upstream branch of your current branch does not match
the name of your current branch.
Configura el nuevo upstream con git push -u origin nombre-nuevo y el problema desaparecerá.
Y si alguien vuelve a publicar la rama antigua después de que la eliminaras, aparecerá de nuevo en el servidor. Bórrala otra vez con git push origin --delete y asegúrate de que esa persona actualiza su copia local.
Recuperar una rama si algo sale mal
Renombrar una rama es una operación segura, pero si en algún momento usas -M sobre una rama con trabajo o borras por error una rama remota, Git ofrece mecanismos para recuperarla.
El reflog guarda el historial de dónde ha apuntado HEAD durante las últimas semanas, por defecto noventa días para los commits alcanzables:
git reflog
b76f45f HEAD@{0}: Branch: renamed refs/heads/feature/pago-con-tarjta to refs/heads/feature/pago-con-tarjeta
b76f45f HEAD@{1}: Branch: renamed refs/heads/feature/pago-con-tarjta to refs/heads/feature/pago-con-tarjeta
b76f45f HEAD@{2}: commit: Añade validación de tarjeta
428cfcd HEAD@{3}: checkout: moving from main to feature/pago-con-tarjta
Con el hash del commit puedes recrear la rama perdida:
git branch feature/recuperada b76f45f
Si eliminaste una rama remota que todavía tienes en local, basta con volver a publicarla. Y si no la tienes en local pero un compañero sí, o tu repositorio todavía conserva la referencia origin/nombre porque no has hecho fetch --prune, puedes crear la rama a partir de ella:
git branch feature/pago-con-tarjta origin/feature/pago-con-tarjta
git push -u origin feature/pago-con-tarjta
Renombrar ramas desde editores y clientes gráficos
No todo el mundo trabaja exclusivamente en la terminal, y la mayoría de editores y clientes gráficos de Git ofrecen una opción para renombrar ramas. Conviene saber qué hacen por debajo para no llevarse sorpresas.
En Visual Studio Code, la paleta de comandos incluye la acción Git: Rename Branch, que ejecuta el equivalente a git branch -m sobre la rama actual. Solo cambia el nombre en local, así que después tendrás que publicar la rama con el nuevo nombre y borrar la antigua del remoto, igual que en la terminal. Los IDE de JetBrains, como IntelliJ IDEA o WebStorm, permiten renombrar desde el menú de ramas y, en versiones recientes, ofrecen también actualizar la rama remota en el mismo paso.
Clientes como GitHub Desktop, GitKraken, Sourcetree o Fork incluyen opciones similares en el menú contextual de cada rama. Algunos realizan únicamente el cambio local y otros preguntan si se desea propagarlo al servidor. Si no estás seguro de lo que ha hecho la herramienta, la terminal te lo dirá en un segundo:
git branch -vv
git ls-remote --heads origin
El segundo comando consulta directamente al servidor la lista de ramas que existen en él, sin depender de las referencias almacenadas en tu copia local, que pueden estar desactualizadas si no has hecho fetch.
Buenas prácticas antes de renombrar una rama compartida
Renombrar una rama personal no tiene ningún riesgo, pero cuando la rama la usan varias personas o sistemas automáticos conviene seguir una pequeña lista de comprobación.
Primero, asegúrate de que no hay trabajo pendiente de publicar. Ejecuta git status y confirma que tu rama local está sincronizada con la remota, sin commits por enviar ni por recibir.
Segundo, revisa qué depende del nombre de la rama. Además de las solicitudes de integración, pueden existir flujos de integración continua con filtros por rama, entornos de vista previa que se despliegan a partir de su nombre, reglas de protección o integraciones con gestores de tareas que vinculan la rama a una incidencia.
Tercero, elige un momento con poca actividad y comunica el cambio con antelación, indicando el nombre antiguo, el nuevo y los comandos que cada persona debe ejecutar.
Cuarto, haz el cambio desde la interfaz de la plataforma siempre que sea posible, porque actualiza automáticamente muchas de esas dependencias.
Y quinto, verifica el resultado tanto en local como en el servidor antes de dar el cambio por terminado.
Conclusiones
Renombrar una rama en Git es una tarea sencilla una vez que se entiende qué es una rama: un puntero con nombre a un commit. En local, el comando git branch -m cambia ese nombre de forma instantánea, tanto si estás situado en la rama como si no, y -M permite forzar el cambio cuando es necesario.
En el remoto no existe un renombrado directo desde la línea de comandos de Git. El procedimiento consiste en publicar la rama con su nuevo nombre usando git push -u, que además configura el seguimiento, y eliminar después el nombre antiguo con git push origin --delete. Hacerlo en ese orden garantiza que el trabajo no exista nunca solo en tu equipo.
Cuando la rama es compartida o tiene solicitudes de integración abiertas, renombrarla desde la interfaz de la plataforma, como permite GitHub, evita cerrar pull requests y actualiza automáticamente reglas y redirecciones. En cualquier caso, hay que avisar al equipo y facilitarle los comandos para actualizar sus copias locales.
El cambio de master a main sigue el mismo proceso, añadiendo la actualización de la rama por defecto en la plataforma, de la referencia HEAD del remoto y de todos los flujos de integración continua que dependan del nombre. Configurar init.defaultBranch evita tener que repetirlo en los repositorios nuevos.
Por último, adoptar una convención de nombres clara desde el principio reduce la necesidad de renombrar ramas, y el reflog está siempre disponible como red de seguridad si algo sale mal.