Sinopsis
git describe [--tags] [--always] [--dirty] [<commit>]Descripción
El comando git describe produce un nombre legible por humanos para un commit basado en el tag alcanzable más reciente. La salida luce como v1.4.2-13-gabc1234, lo que significa 13 commits despues del tag v1.4.2, en SHA abc1234. Si el commit está exactamente en un tag, solo se imprime el nombre del tag.
Los sistemas de build usan git describe para incrustar cadenas de versión en los binarios. Con --dirty, la salida incluye un sufijo -dirty cuando el árbol de trabajo tiene cambios no commiteados, perfecto para marcar builds de desarrollo.
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.
Opciones comunes
| Opción | Descripción |
|---|---|
--tags | Use lightweight tags as well as annotated. |
--always | Fall back to abbreviated SHA if no tag is reachable. |
--dirty[=<mark>] | Append a marker if the working tree is dirty. |
--long | Always show the long format, even when at a tag. |
--match <pattern> | Only consider tags matching a glob. |
--abbrev=<n> | Use n hex digits for the SHA. |
--contains | Show the earliest tag that contains the commit. |
Ejemplos
git describe
# e.g. v2.1.0-3-g1a2b3c4
git describe --tags --dirty --always
# Robust version string for build scripts
git describe --match 'v[0-9]*'
# Only consider semver-style tags
git describe --contains abc123
# Find the first release that includes a commitErrores comunes
If your repo has only lightweight (non-annotated) tags, plain git describe says "fatal: No names found." Use --tags. Shallow clones may have no reachable tags at all — fetch tags explicitly with git fetch --tags.
Comandos relacionados
git tag, git log, git rev-parse, git show