Introduction

Les tags sont des références nommées vers des commits spécifiques. Contrairement aux branches, les tags ne sont pas censés bouger. Ils sont parfaits pour marquer les releases (v1.0.0) et autres points historiques.

Deux types de tags

• Lightweight : juste une ref pointant vers un commit. Pas de métadonnées.
• Annotated : un objet Git complet avec tagger, date, message et signature GPG optionnelle. Utilisez ceux-ci pour les releases.

Créer des tags

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"         # signé GPG

Par défaut, les tags s'attachent à HEAD. Pour étiqueter un commit spécifique :

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

Lister et inspecter

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

Pousser les tags

Les tags ne sont pas poussés par défaut :

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

--follow-tags est le défaut recommandé pour les pipelines de release.

Supprimer des tags

git tag -d v1.0.0                     # local
git push origin --delete v1.0.0       # distant

Faire un checkout d'un tag

git switch --detach v1.0.0
# ou pour baser une branche hotfix sur un tag
git switch -c hotfix/1.0.1 v1.0.0

Vérifier les signatures

git tag -v v1.0.0

Nécessite la clé publique du tagger dans votre trousseau GPG.

Décrire les builds avec git describe

Une fois que votre dépôt a des tags annotés, git describe produit des identifiants de build stables qui combinent le dernier tag, la distance et le SHA abrégé :

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

Le suffixe --dirty apparaît si l'arborescence de travail a des changements non commités ; --always retombe sur un SHA nu quand aucun tag n'est atteignable. Les pipelines CI intègrent souvent cette chaîne dans les binaires pour rendre triviaux les rapports de terrain.

Politiques de tagging

Pour les projets supportés à long terme, décidez et documentez :

• Schéma de nommage : v1.2.3, release-2025-04, 1.2.3 (sans préfixe) ?
• Annoté ou signé ?
• Qui est autorisé à pusher des tags ? De nombreux hôtes vous permettent de protéger les noms de tags par des motifs.
• Quelle est la source de vérité : tags-sur-main seulement, ou branches de release avec leurs propres tags ?

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

Choisissez un schéma et tenez-vous-y ; l'historique des tags est plus difficile à migrer que l'historique des commits.

Erreurs fréquentes

Utiliser des tags lightweight pour les releases. Ils manquent de date, d'auteur et de message, ce qui rend les pistes d'audit pénibles. Utilisez toujours -a ou -s pour les releases. Déplacer un tag après publication ; les utilisateurs en aval ne récupéreront pas le changement proprement. Créez un nouveau tag (par ex. v1.0.1) à la place. Oublier de pousser les tags et se demander pourquoi votre page de releases est vide ; rappelez-vous git push --tags ou --follow-tags. Enfin, nommer des tags avec des caractères en conflit avec les refs (un tag et une branche nommés release créeront une ambiguïté) ; utilisez une convention claire comme v<semver> pour les releases.