Sinopsis
git update-ref [-d] [--create-reflog] <ref> <newvalue> [<oldvalue>]Descripción
El comando git update-ref es plumbing para crear, mover o eliminar refs (branches, tags, refs personalizadas). Soporta compare-and-set para evitar carreras: la actualización solo tiene éxito si el valor actual coincide con el esperado.
Usado por scripts que manipulan refs directamente. Más seguro que editar archivos bajo .git/refs/ a mano.
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
Most developers never need this. Use it when writing automation that creates, moves, or deletes refs in custom namespaces (notes, replace, custom systems), or when a porcelain command isn't appropriate (e.g., creating a ref that points at an arbitrary tree).
Opciones comunes
| Opción | Descripción |
|---|---|
-d <ref> [<oldvalue>] | Delete a ref (optionally compare-and-swap). |
--no-deref | Don't follow symbolic refs. |
--create-reflog | Create a reflog if missing. |
-m <reason> | Reflog reason for this update. |
--stdin | Read updates from stdin (atomic batch). |
Ejemplos
git update-ref refs/heads/feature abc123
# Move feature branch to commit abc123
git update-ref -d refs/heads/old-experiment
# Delete a branch ref directly
git update-ref refs/notes/ci HEAD def456
# Move a custom notes ref atomically
# Atomic multi-ref update via stdin:
printf 'update refs/heads/main %s\nupdate refs/heads/dev %s\n' "$NEW1" "$NEW2" | \
git update-ref --stdinErrores comunes
Bypassing safety by editing .git/refs/ files directly can corrupt packed refs or skip reflog entries. Always use update-ref. Forgetting to provide <oldvalue> defeats the compare-and-swap protection — provide it whenever you can.
Comandos relacionados
git symbolic-ref, git pack-refs, git for-each-ref, git branch