Introduction

Git supporte deux types de tags : lightweight, qui sont juste des refs pointant vers des commits, et annotés, qui sont des objets Git complets avec métadonnées. Utilisez les tags annotés pour les releases.

Créer

git tag v1.0.0                          # lightweight
git tag -a v1.0.0 -m "1.0 GA"           # annoté
git tag -s v1.0.0 -m "Signed"           # annoté signé GPG
git tag -a v1.0.0 a1b2c3d -m "..."     # tagger un commit spécifique

Ce que les tags annotés stockent

git cat-file -t v1.0.0
# tag
git cat-file -p v1.0.0
# object <commit-sha>
# type commit
# tag v1.0.0
# tagger Ada <[email protected]> 1714300000 +0000
#
# 1.0 GA

Un tag annoté est son propre objet. Il a son propre SHA distinct du commit vers lequel il pointe, un tagger et une date, un message et une signature optionnelle.

Ce que les tags lightweight ne stockent pas

Un tag lightweight est juste refs/tags/v1.0.0 contenant un SHA de commit. Il n'y a pas de message, pas de tagger, pas de signature. git describe, git tag -v et de nombreux outils CI de release supposent des tags annotés et se comportent étrangement avec les lightweight.

Inspecter

git show v1.0.0
git tag -l --format='%(refname:short) %(objecttype) %(taggername) %(subject)'

Les tags lightweight affichent commit comme type d'objet ; les annotés affichent tag.

Signer et vérifier

git tag -s v1.0.0 -m "Signed"
git tag -v v1.0.0
# gpg: Good signature from "Ada Lovelace <[email protected]>"

La signature SSH est aussi supportée dans Git moderne :

git config --global gpg.format ssh
git config --global user.signingkey ~/.ssh/id_ed25519.pub
git tag -s v1.1.0 -m "SSH-signed"

Choisir

• Utilisez annotés pour les releases, tout ce que vous publiez, tout ce que vous signez.
• Utilisez lightweight pour des signets locaux ad hoc (par ex. « se rappeler de ce commit avant un rebase »).

Pousser des tags

git push origin v1.0.0
git push origin --tags
git push --follow-tags         # uniquement tags annotés atteignables depuis les commits poussés

--follow-tags ignore délibérément les tags lightweight, ce qui est généralement ce que vous voulez.

Déréférencement de tag

De nombreuses commandes déréférencent automatiquement un tag annoté vers le commit vers lequel il pointe ; certaines ne le font pas. Utilisez ^{} pour forcer le déréférencement dans les scripts :

git rev-parse v1.0.0           # SHA de l'objet tag (annoté)
git rev-parse v1.0.0^{}        # SHA du commit vers lequel il pointe
git rev-parse v1.0.0^{commit}  # idem, avec assertion de type
git for-each-ref --format='%(refname:short) %(*objectname)' refs/tags

L'espace réservé %(*objectname) donne le commit déréférencé pour les tags et est vide pour les refs non-tag. Ce motif est essentiel pour les scripts de release qui ont besoin d'un SHA de commit à partir d'un nom de tag.

Erreurs fréquentes

Tagger des releases avec un simple git tag v1.0 et manquer le tagger/date/message dans les logs d'audit. Passez toujours -a ou -s. Déplacer un tag publié vers un nouveau commit (« force-tag ») ; les utilisateurs en aval ont déjà mis en cache l'ancien SHA et peuvent ne pas récupérer le changement. Émettez v1.0.1 à la place. Utiliser des tags lightweight comme signets nommés partagés dans une équipe ; si vous devez partager, préférez les branches ou tags annotés. Enfin, attendre que git describe fonctionne sans tags annotés ; par défaut il ne compte que les annotés (--tags permet d'inclure les lightweight, avec des réserves).