Introduzione

I tag sono riferimenti nominati a commit specifici. A differenza dei branch, i tag non sono pensati per muoversi. Sono perfetti per marcare release (v1.0.0) e altri punti storici.

Due tipi di tag

• Lightweight: solo un ref che punta a un commit. Nessun metadato.
• Annotated: un oggetto Git completo con tagger, data, messaggio e firma GPG opzionale. Usali per le release.

Creare i tag

git tag v1.0.0                          # lightweight
git tag -a v1.0.0 -m "First stable release"   # annotated
git tag -s v1.0.0 -m "Signed release"         # firmato GPG

Per impostazione predefinita i tag si attaccano a HEAD. Per taggare un commit specifico:

git tag -a v0.9.0 a1b2c3d -m "Beta"

Elencare e ispezionare

git tag
git tag -l "v1.*"
git show v1.0.0
git tag -l --format='%(refname:short) %(taggerdate:short) %(subject)'

Pushare i tag

I tag non vengono pushati per default:

git push origin v1.0.0
git push origin --tags                # tutti i tag
git push --follow-tags                # solo tag raggiungibili dai commit pushati

--follow-tags è il default consigliato per le pipeline di rilascio.

Cancellare i tag

git tag -d v1.0.0                     # locale
git push origin --delete v1.0.0       # remoto

Checkout di un tag

git switch --detach v1.0.0
# oppure per basare un branch hotfix su un tag
git switch -c hotfix/1.0.1 v1.0.0

Verificare le firme

git tag -v v1.0.0

Richiede la chiave pubblica del tagger nel tuo keyring GPG.

Descrivere build con git describe

Una volta che il tuo repo ha tag annotated, git describe produce identificatori di build stabili che combinano l'ultimo tag, la distanza e lo SHA abbreviato:

git describe
# v1.2.3-7-gabc1234
git describe --always --dirty
# v1.2.3-7-gabc1234-dirty

Il suffisso --dirty appare se la working tree ha modifiche non committate; --always ricade su uno SHA nudo quando nessun tag è raggiungibile. Le pipeline CI spesso incorporano questa stringa nei binari per rendere triviale la risoluzione di problemi sul campo.

Politiche di tagging

Per progetti supportati a lungo termine, decidi e documenta:

• Schema di naming: v1.2.3, release-2025-04, 1.2.3 (senza prefisso)?
• Annotated o firmati?
• Chi può pushare i tag? Molti host ti permettono di proteggere i nomi dei tag con pattern.
• Qual è la fonte di verità: tag solo su main, o release branch con i propri tag?

git for-each-ref --sort=-creatordate --format='%(refname:short) %(creatordate:short)' refs/tags | head

Scegli uno schema e attieniti ad esso; la storia dei tag è più difficile da migrare di quella dei commit.

Errori comuni

Usare tag lightweight per le release. Mancano di data, autore e messaggio, il che rende dolorose le tracce di audit. Usa sempre -a o -s per le release. Spostare un tag dopo che è pubblicato; gli utenti a valle non recepiranno il cambiamento in modo pulito. Crea un nuovo tag (es. v1.0.1). Dimenticare di pushare i tag e chiedersi perché la tua release page è vuota; ricorda git push --tags o --follow-tags. Infine, nominare tag con caratteri che confliggono con i ref (un tag e un branch chiamati release creeranno ambiguità); usa una convenzione chiara come v<semver> per le release.