Tags Git : versionner et publier vos releases

Les tags Git marquent un point précis de l'historique, typiquement une release. Contrairement aux branches (qui bougent à chaque commit), un tag est un pointeur fixe vers un commit spécifique. Ce guide vous apprend à créer, gérer et pousser des tags, en suivant les conventions du Semantic Versioning.

Prérequis : enregistrer des modifications et consulter l'historique.

Ce que vous allez apprendre

La différence entre tags légers et tags annotés
Créer, lister, supprimer des tags
Pousser des tags vers un dépôt distant
Adopter le Semantic Versioning (SemVer)

Tags légers vs annotés

Git propose deux types de tags, et la différence n'est pas cosmétique. Un tag léger est un simple pointeur vers un commit, rien d'autre. Un tag annoté est un véritable objet Git stocké dans le dépôt, avec son auteur, sa date, son message et la possibilité d'une signature GPG. C'est cette traçabilité qui en fait la forme attendue pour une release : on sait qui a publié la version et quand. Réservez le tag léger aux repères de travail que vous ne pousserez pas.

Type	Contenu	Usage
Tag léger	Pointeur simple vers un commit, sans métadonnées	Marquage temporaire, usage local
Tag annoté	Objet Git complet : auteur, date, message, signable GPG	Recommandé pour les releases

Créer un tag annoté

C'est la forme recommandée pour les releases :

git tag -a v1.0.0 -m "Première version stable"

-a : créer un tag annoté
-m : le message associé (comme pour un commit)

Vérification :

git show v1.0.0

Sortie attendue :

tag v1.0.0
Tagger: Stéphane ROBERT <stephane@example.com>
Date:   Fri Mar 28 14:30:00 2026 +0100

Première version stable

commit 3f7a2b1c8e9d4f5a6b7c8d9e0f1a2b3c4d5e6f7a (HEAD -> main, tag: v1.0.0)
Author: Stéphane ROBERT <stephane@example.com>
Date:   Fri Mar 28 14:30:00 2026 +0100

    Ajout de la page de contact

Le tag annoté stocke le nom du tagger, la date et le message en plus de pointer vers le commit.

Créer un tag léger

Pour un marquage rapide sans métadonnées :

git tag v1.0.0-beta

Pas de -a, pas de -m. Le tag pointe simplement vers le commit courant, sans information supplémentaire.

Tagger un commit passé

Vous avez oublié de tagger au moment du commit ? Pas de problème :

git log --oneline -5

3f7a2b1 Ajout de la page de contact
a1b2c3d Correction du bug d'affichage
9c8d7e6 Refactoring du CSS
f5e4d3c Ajout de la page d'accueil
1a2b3c4 Initial commit

Taggez un commit spécifique :

git tag -a v0.9.0 -m "Version beta" a1b2c3d

Lister les tags

Au fil des releases, la liste des tags devient votre table des matières des versions. Trois variantes de la commande couvrent les besoins courants : la liste brute, le filtrage par motif pour ne voir qu'une série de versions, et l'affichage des messages pour retrouver le contexte de chaque release sans ouvrir chaque tag.

git tag

Sortie attendue :

v0.9.0
v1.0.0
v1.0.0-beta

Filtrer par pattern :

git tag -l "v1.*"

v1.0.0
v1.0.0-beta

Pour voir les tags avec leurs messages :

git tag -n

v0.9.0          Version beta
v1.0.0          Première version stable
v1.0.0-beta     Ajout de la page de contact

Pour un tag annoté, git tag -n affiche son message d'annotation. Pour un tag léger, qui n'en a pas, il affiche à la place le résumé du commit pointé, ici Ajout de la page de contact. C'est une autre raison de préférer les tags annotés pour les releases : leur description ne dépend pas du message de commit.

Pousser les tags vers un remote

Par défaut, git push ne pousse pas les tags. Il faut le faire explicitement.

Pousser un tag spécifique

C'est la forme à privilégier au quotidien : vous poussez la version que vous venez de créer, et rien d'autre, ce qui évite de publier par mégarde des tags de test restés en local.

git push origin v1.0.0

Pousser tous les tags

git push origin --tags

--tags pousse tous les tags locaux, y compris les tags légers et les tags de test. Pour pousser uniquement les tags annotés, utilisez :

git push origin --follow-tags

C'est souvent le comportement souhaité. Vous pouvez le rendre par défaut :

git config --global push.followTags true

Supprimer un tag

Supprimer un tag local

Supprimer le tag en local ne touche pas le dépôt distant : si le tag y a déjà été poussé, il y reste jusqu'à une suppression explicite, traitée juste après.

git tag -d v1.0.0-beta

Supprimer un tag distant

La suppression distante mérite prudence : d'autres personnes ont peut-être déjà récupéré ce tag, et le retirer ne l'efface pas de leurs clones. Réservez cette opération aux tags publiés par erreur, jamais à une release que d'autres consomment déjà.

git push origin --delete v1.0.0-beta

Ou avec la syntaxe refspec :

git push origin :refs/tags/v1.0.0-beta

Semantic Versioning (SemVer)

Nommer ses versions au hasard rend impossible de savoir, d'un coup d'œil, si une mise à jour est risquée. Le Semantic Versioning répond à ce besoin en codant l'impact du changement dans le numéro lui-même : à la lecture de v1.4.2, un utilisateur sait que passer à v1.5.0 n'introduit rien de cassant, alors que v2.0.0 exigera une migration. Ce sont ces trois chiffres, et ce qu'ils promettent, que détaille le tableau ci-dessous.

vMAJEUR.MINEUR.PATCH

Composant	Quand l'incrémenter	Exemple
MAJEUR	Changement incompatible (breaking change)	`v1.0.0` → `v2.0.0`
MINEUR	Nouvelle fonctionnalité rétrocompatible	`v1.0.0` → `v1.1.0`
PATCH	Correction de bug rétrocompatible	`v1.0.0` → `v1.0.1`

Exemples concrets

Cette progression illustre le cycle de vie typique d'un projet. Notez la frontière du v1.0.0 : tant que le numéro majeur reste à zéro, la convention autorise des changements cassants entre versions mineures, car l'API n'est pas encore figée. Passer à v1.0.0 est donc un engagement, celui de ne plus casser la compatibilité sans incrémenter le numéro majeur.

v0.1.0    → Première version utilisable (pas encore stable)
v0.2.0    → Ajout d'une fonctionnalité
v0.2.1    → Correction d'un bug
v1.0.0    → Première release stable (API publique figée)
v1.1.0    → Nouvelle fonctionnalité rétrocompatible
v2.0.0    → Breaking change (migration requise)

Suffixes courants

v1.0.0-alpha    → Version très préliminaire
v1.0.0-beta     → Version de test
v1.0.0-rc.1     → Release Candidate 1
v1.0.0          → Version stable

Workflow complet : tagger une release

Voici l'enchaînement à reproduire pour chaque version publiée. L'ordre a son importance : on vérifie que l'arbre de travail est propre avant de tagger, on crée un tag annoté, puis on le pousse explicitement, car git push seul laisserait le tag en local. La dernière étape confirme, côté serveur, que la release est bien visible pour les autres.

Vérifiez que tout est propre
Fenêtre de terminal
```
git status
git log --oneline -5
```

Créez le tag annoté

git tag -a v1.2.0 -m "Ajout de l'authentification OAuth"

Poussez le tag
Fenêtre de terminal
```
git push origin v1.2.0
```
Vérifiez sur le remote
Fenêtre de terminal
```
git ls-remote --tags origin
```

Dépannage : problèmes courants

La plupart des soucis avec les tags se ramènent à deux causes : un tag non poussé, qui reste invisible sur la forge, et un tag placé sur le mauvais commit, car il pointe par défaut sur HEAD au moment de sa création. Le tableau associe chaque symptôme à sa cause et à la commande de correction.

Symptôme	Cause probable	Solution
`error: tag 'v1.0.0' already exists`	Un tag avec ce nom existe déjà	Supprimez-le d'abord (`git tag -d v1.0.0`) ou utilisez un autre nom
Les tags n'apparaissent pas sur GitHub/GitLab	Tags non poussés	`git push origin --tags`
`git describe` affiche un résultat inattendu	Pas de tag annoté dans l'historique	`git describe` cherche les tags annotés par défaut. Utilisez `--tags` pour inclure les légers
Tag sur le mauvais commit	Le tag pointe vers HEAD au moment de la création	Supprimez-le et recréez-le sur le bon commit : `git tag -a v1.0.0 SHA`

Quel tag utiliser ?

Situation	Tag recommandé	Commande
Release publique (v1.0.0, v2.3.1...)	Annoté	`git tag -a v1.0.0 -m "..."`
Marquer un point de repère temporaire	Léger	`git tag wip-avant-refacto`
Tag qui sera poussé et visible sur GitHub/GitLab	Annoté	`git tag -a`
Tag local uniquement, jamais poussé	Léger	`git tag`
Release avec signature GPG	Annoté + signé	`git tag -s v1.0.0 -m "..."`

En pratique : utilisez toujours le tag annoté sauf pour les repères temporaires. git describe et les plateformes comme GitHub reconnaissent les tags annotés en priorité pour les releases.

À retenir

Tags annotés (git tag -a) sont recommandés pour les releases : ils contiennent auteur, date et message
Tags légers sont de simples pointeurs, pour un usage temporaire
git push ne pousse pas les tags automatiquement, utilisez git push origin --tags ou --follow-tags
Semantic Versioning (MAJEUR.MINEUR.PATCH) est la convention standard
Utilisez git tag -d en local et git push --delete pour le remote

FAQ : git tag

Comment créer un tag Git annoté ?

Utilisez git tag -a v1.0.0 -m "message" : cela crée un tag annoté, stocké comme un objet Git complet avec auteur, date et message. C'est la forme recommandée pour marquer une release, contrairement au tag léger qui n'est qu'un pointeur.

Un tag annoté est la forme recommandée pour une release :

git tag -a v1.0.0 -m "Version 1.0.0 : première release stable"

Contrairement au tag léger, il est stocké comme un objet Git complet : il porte un auteur, une date, un message et peut être signé (-s). C'est indispensable pour tracer qui a publié quelle version et quand.

Quelle différence entre un tag léger et un tag annoté ?

Un tag léger est un simple pointeur vers un commit, sans métadonnées. Un tag annoté est un objet Git complet avec auteur, date, message et signature possible. On réserve le tag léger à un marque-page temporaire et on utilise l'annoté pour les releases publiées.

Deux natures très différentes :

Critère	Tag léger	Tag annoté
Nature	Pointeur simple	Objet Git complet
Métadonnées	Aucune	Auteur, date, message
Signature	Non	Possible (`-s`)
Usage	Marque-page perso	Release publiée

git tag v1.0-tmp            # léger (pas de -a ni -m)
git tag -a v1.0.0 -m "..."  # annoté

Règle : annoté pour tout ce qui est publié ou partagé, léger pour un repère temporaire local.

Comment pousser un tag Git vers le remote ?

git push ne pousse pas les tags par défaut. Utilisez git push origin v1.0.0 pour un tag précis, ou git push origin --tags pour tous les tags. Sur un dépôt de release, on pousse le tag après avoir validé le commit correspondant.

Point important : git push n'envoie pas les tags par défaut. Il faut les pousser explicitement :

git push origin v1.0.0     # un tag précis
git push origin --tags     # tous les tags locaux

Sur un dépôt de release, poussez le tag après avoir validé le commit qu'il pointe : beaucoup de pipelines CI/CD se déclenchent sur l'arrivée d'un tag v* pour construire et publier la version.

Comment supprimer un tag Git en local et à distance ?

En local, git tag -d v1.0.0 supprime le tag. À distance, git push origin --delete v1.0.0 le retire du remote. Les deux opérations sont indépendantes : supprimer un tag local ne le retire pas du serveur, et inversement.

La suppression se fait en deux endroits indépendants :

git tag -d v1.0.0                    # supprime le tag EN LOCAL
git push origin --delete v1.0.0     # supprime le tag SUR LE REMOTE

Attention : supprimer un tag déjà publié peut casser les références de ceux qui l'ont récupéré ou des pipelines qui s'en servent. Sur une release diffusée, préférez publier une nouvelle version corrective plutôt que de retirer un tag existant.

Comment tagger un commit passé ?

Ajoutez le hash du commit à la fin de la commande : git tag -a v1.0.0 <hash>. Git place le tag sur ce commit précis au lieu de HEAD. Pratique pour marquer rétroactivement une version dont le commit a déjà été fait.

Il suffit d'indiquer le hash du commit à la fin de la commande :

git log --oneline               # retrouver le hash du commit à tagger
git tag -a v1.0.0 9b7d3e2 -m "Version 1.0.0"

Sans hash, Git tague HEAD (le dernier commit). Avec le hash, il place le tag sur le commit précis, ce qui permet de marquer rétroactivement une version dont le commit a déjà été fait il y a plusieurs jours.

Comment lister les tags Git ?

git tag ou git tag -l affiche tous les tags. On filtre avec un motif comme git tag -l "v1.*", et on trie par version avec git tag --sort=-v:refname pour voir les plus récents en premier. git show v1.0.0 détaille un tag précis.

La commande de base et ses variantes utiles :

git tag                          # tous les tags
git tag -l "v1.*"                # filtrer par motif
git tag --sort=-v:refname        # trier par version (récent en premier)
git show v1.0.0                  # détail d'un tag (message, commit)

Le tri par version (-v:refname) est plus pertinent que l'ordre alphabétique par défaut, qui placerait v1.10.0 avant v1.9.0.

Prochaines étapes

Alias et productivité Git Accélérez votre workflow quotidien avec des alias personnalisés.

Les branches Git en bref Les tags marquent des versions, les branches permettent le travail parallèle.

Annuler des modifications Revenez en arrière si vous avez taggé trop tôt.