Sinopsis
git symbolic-ref [--short] <name> [<ref>]
git symbolic-ref --delete <name>Descripción
El comando git symbolic-ref lee y escribe refs simbólicas: refs cuyo valor es otro nombre de ref en lugar de un SHA. HEAD es el ejemplo canónico (apunta a refs/heads/main).
Usado para inspeccionar el branch actual desde scripts y para configurar el HEAD predeterminado de remotos sin hacer un checkout.
En el uso diario, este comando se integra estrechamente con alias de shell, plugins de editor e integración continua. Los usuarios avanzados a menudo añaden alias que combinan los flags que siempre pasan. El formato de salida puede personalizarse vía configuración de Git. Cuando algo sale mal, ejecuta el comando con GIT_TRACE=1 para revelar las llamadas plumbing subyacentes.
Entender cómo este comando interactúa con el resto del modelo de datos de Git rinde dividendos. Cada comando opera sobre algún subconjunto de las piezas (objetos, index, refs, árbol de trabajo), y saber cuáles toca ayuda a predecir resultados y a recuperarse de errores.
Cuándo usar
Use this when you need to switch HEAD without touching the working tree (e.g., during a custom migration), or when scripting around the default-branch concept. Most users only ever read symbolic refs via git rev-parse --abbrev-ref HEAD.
Opciones comunes
| Opción | Descripción |
|---|---|
--short | Print the short name (e.g. main). |
--delete | Delete the symbolic ref. |
--quiet | Don't print error if ref is missing. |
-m <reason> | Reflog reason for changes. |
Ejemplos
git symbolic-ref HEAD
# refs/heads/main
git symbolic-ref --short HEAD
# main
git symbolic-ref refs/remotes/origin/HEAD refs/remotes/origin/main
# Set the default branch indicator on origin
git symbolic-ref HEAD refs/heads/develop
# Switch HEAD without touching working tree (advanced!)Errores comunes
Switching HEAD via symbolic-ref doesn't update the working tree — files won't change. Use git switch for the everyday case. Setting origin/HEAD incorrectly confuses tools that look up the default branch.
Comandos relacionados
git update-ref, git switch, git rev-parse, git remote set-head