Sinossi
git describe --tags --dirty --always [--match 'v[0-9]*']Descrizione
Questa pagina copre git describe da un'angolatura di versioning: come progettare uno schema di tag che guida stringhe di versione di build riproducibili. L'output di git describe è ampiamente usato dai sistemi di build (Make, CMake, Cargo, script npm) per generare una stringa di versione che include un tag base più distanza e SHA.
Il pattern raccomandato: usa tag annotated semver come v1.2.3; gli script di build chiamano git describe --tags --dirty --always --match 'v[0-9]*'; la stringa risultante viene incorporata nei binari tramite un header generato o costante. Questo produce versioni deterministiche che riflettono sia l'ultima release che qualsiasi lavoro non rilasciato da allora.
Nell'uso quotidiano, git describe (versioning) si integra con alias e CI.
Capire il modello dati di Git aiuta a prevedere i risultati.
Opzioni comuni
| Opzione | Descrizione |
|---|---|
--tags | Usa anche tag lightweight oltre agli annotated. |
--dirty[=<mark>] | Aggiunge un marker se la tree è sporca. |
--always | Ricade su SHA abbreviato quando nessun tag è raggiungibile. |
--long | Forza il formato lungo anche a un tag. |
--match <pattern> | Restringe a tag corrispondenti a un pattern (es. esclude nightly-*). |
--exclude <pattern> | Esclude tag corrispondenti. |
--abbrev=<n> | Lunghezza dello SHA abbreviato. |
Esempi
# Genera una stringa di versione per una build
VERSION=$(git describe --tags --dirty --always --match 'v[0-9]*')
echo "${VERSION#v}" > VERSION
# In un Makefile:
VERSION := $(shell git describe --tags --dirty --always)
CFLAGS += -DVERSION="\"$(VERSION)\""
# Nello script prepublish di package.json:
node -e "p=require('./package.json'); p.version=process.env.VERSION; require('fs').writeFileSync('package.json', JSON.stringify(p,null,2))"Errori comuni
Usare tag lightweight rompe git describe senza --tags. Includere tag di release candidate o nightly nel tuo pattern di match produce versioni rumorose per build stabili. I clone shallow CI possono non avere tag affatto — scaricali esplicitamente: git fetch --tags --unshallow.
Comandi correlati
git tag, git rev-parse, git for-each-ref, git log