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 :

Type	Contenu	Usage
Tag léger	Pointeur simple vers un commit (comme un signet)	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

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     (pas de message — tag léger)

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

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

git tag -d v1.0.0-beta

Supprimer un tag distant

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)

La convention de nommage la plus répandue pour les tags :

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

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

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

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

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.