Sinopsis
git describe --tags --dirty --always [--match 'v[0-9]*']Descripción
git describe con tags anotados es la base más simple para versionado de software automático. Los sistemas de build invocan git describe para producir cadenas de versión que incluyen el último tag, distancia de commits y hash abreviado: v1.4.2-13-gabc1234.
Combina con --dirty para marcar builds de desarrollo. Para CI determinístico, asegúrate de que el clone incluya tags (no --depth=1 sin --tags).
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 as well as annotated tags. |
--dirty[=<mark>] | Append a marker if the tree is dirty. |
--always | Fall back to abbreviated SHA when no tag is reachable. |
--long | Force long format even at a tag. |
--match <pattern> | Restrict to tags matching a pattern (e.g. exclude nightly-*). |
--exclude <pattern> | Exclude matching tags. |
--abbrev=<n> | Abbrev SHA length. |
Ejemplos
# Generate a version string for a build
VERSION=$(git describe --tags --dirty --always --match 'v[0-9]*')
echo "${VERSION#v}" > VERSION
# In a Makefile:
VERSION := $(shell git describe --tags --dirty --always)
CFLAGS += -DVERSION="\"$(VERSION)\""
# In package.json prepublish script:
node -e "p=require('./package.json'); p.version=process.env.VERSION; require('fs').writeFileSync('package.json', JSON.stringify(p,null,2))"Errores comunes
Using lightweight tags breaks git describe without --tags. Including release candidate or nightly tags in your match pattern produces noisy versions for stable builds. Shallow CI clones may have no tags at all — fetch them explicitly: git fetch --tags --unshallow.
Comandos relacionados
git tag, git rev-parse, git for-each-ref, git log