git tag

Qu'est-ce qu'un tag Git

Un tag est une référence nommée qui pointe vers un commit spécifique dans votre historique Git. Contrairement à une branche, qui avance à chaque commit, un tag reste fixé sur le commit pour lequel il a été créé. Cela en fait l'outil idéal pour marquer des points importants et permanents dans un projet — le plus souvent des versions de publication telles que v1.0.0 ou v2.3.1.

Cette page explique comment créer les deux types de tags (annoté et léger), comment les lister et les filtrer, comment tagger des commits passés, et comment pousser, inspecter et supprimer des tags.

Créer un tag Git

Pour créer un tag Git, exécutez la commande ci-dessous :

git tag

git tag <name-of-tag>

Lors de la création d'un tag, remplacez <name-of-tag> par un identifiant sémantique pour l'état du dépôt — par exemple v1.3. Git prend en charge deux types de tags : annotés et légers. La principale différence entre eux réside dans la quantité de métadonnées qu'ils stockent.

Tags annotés vs. tags légers

Choisir le bon type de tag est plus important qu'il n'y paraît :

• Les tags annotés sont stockés en tant qu'objets complets dans la base de données Git. Ils enregistrent le nom, l'adresse e-mail et la date du créateur du tag, contiennent un message de tag, et peuvent être signés et vérifiés cryptographiquement avec GPG (GNU Privacy Guard). Utilisez-les pour les versions publiées et tout ce que vous partagez avec d'autres.
• Les tags légers sont simplement un nom pointant vers un commit — sans métadonnées supplémentaires, sans message, sans signature. Ils se comportent comme un signet privé. Utilisez-les pour des marqueurs temporaires ou locaux.

Pour les versions publiées, préférez les tags annotés afin que l'historique enregistre qui a tagué la version et quand.

Tags annotés

Git stocke les tags annotés en tant qu'objets complets dans sa base de données. Ils contiennent des métadonnées supplémentaires, telles que le nom, l'adresse e-mail et la date du créateur du tag. Comme les commits, les tags annotés incluent un message de tag.

L'exécution de la commande ci-dessous crée un nouveau tag annoté avec l'identifiant v1.3. L'éditeur de texte par défaut configuré s'ouvrira alors, vous invitant à saisir un message de tag.

git annotated tag

git tag -a v1.3

Pour fournir le message directement en ligne et ignorer l'éditeur, utilisez l'option -m :

git annotated tag with inline message

git tag -a v1.3 -m "Release version 1.3"

Tags légers

La commande ci-dessous crée un tag léger identifié comme v1.3-lw. Les tags légers sont créés sans les options -a, -s ou -m. Ils stockent simplement un pointeur vers un objet commit spécifique dans le répertoire .git/refs/tags/.

git lightweight tag

git tag v1.3-lw

Liste des tags

Exécutez la commande ci-dessous pour lister les tags enregistrés :

git tag command

git tag

En résultat, vous verrez une sortie similaire à celle-ci :

git tag output

v0.10.0
v0.10.0-rc1
v0.11.0
v0.11.0-rc1
v0.11.1
v0.11.2
v0.12.0
v0.12.0-rc1
v0.12.1
v0.12.2
v0.13.0
v0.13.0-rc1
v0.13.0-rc2

Vous pouvez utiliser l'option -l avec une expression générique pour filtrer la liste des tags :

git tag with wildcard

git tag -l *-rc*
v0.10.0-rc1
v0.11.0-rc1
v0.12.0-rc1
v0.13.0-rc1
v0.13.0-rc2
v0.14.0-rc1
v0.9.0-rc1
v15.0.0-rc.1
v15.0.0-rc.2
v15.4.0-rc.3

Tagger des commits anciens

Par défaut, git tag crée un tag sur le commit référencé par HEAD. Vous pouvez également passer une référence de commit spécifique pour tagger un commit plus ancien à la place. Exécutez la commande git log pour afficher les commits plus anciens. Dans l'exemple ci-dessous, un commit de fusion est utilisé pour le nouveau tag. Pour référencer un commit spécifique, fournissez son hash SHA :

git log

git log --pretty=oneline
29389857951b64cf874c3557a0f3547bd83b899a Merging branch 'crossword'
b4a5697498bd301d84096da251c98a07c7723e65 init method for crossword
89f3aaab4479697da7686c15f77a3d64d9165190 little changes in logic
3a4a271eda8725415634dd79daabbc4d9b6008e Merging branch 'how-it-works'

Exécutez la commande git tag pour créer un nouveau tag annoté avec l'identifiant v1.2 pour le commit sélectionné dans l'exemple précédent :

git tag for old commits

git tag -a v1.2 29389857951b64cf874c3557a0f3547bd83b899a

Remplacer des tags existants

Tenter de créer un tag avec un identifiant existant entraînera une erreur. Utilisez l'option -f (force) pour mettre à jour un tag existant, ce qui écrasera son contenu précédent.

git tag replacing old tags

git tag -a -f v1.3 29389857951b64cf874c3557a0f3547bd83b899a

Pousser des tags vers le dépôt distant

Les tags ne sont pas envoyés automatiquement avec git push — par défaut, git push transfère les commits mais laisse vos tags de côté. Vous devez les pousser explicitement pour que quiconque clone le dépôt les reçoive.

Pour pousser un seul tag, passez son nom à git push :

git tag, pushing to remote

git push origin v1.3
Counting objects: 9, done.
Delta compression using up to 5 threads.
Compressing objects: 100% (8/8), done.
Writing objects: 100% (12/12), 2.05 KiB | 0 bytes/s, done.
Total 12 (delta 3), reused 0 (delta 0)
To [email protected]:gr8/gittagdocs.git
* [new tag] v1.3 -> v1.3

Pour pousser tous les tags locaux que le dépôt distant ne possède pas encore, utilisez l'option --tags :

git push all tags

git push origin --tags

Inspecter un tag

Utilisez git show pour afficher les données stockées dans un tag. Pour un tag annoté, il affiche les métadonnées du tag (créateur, date, message) suivies du commit vers lequel il pointe :

git show on an annotated tag

git show v1.3
tag v1.3
Tagger: Jane Doe <[email protected]m>
Date:   Mon Jun 9 14:21:03 2025 +0000

Release version 1.3

commit 29389857951b64cf874c3557a0f3547bd83b899a
Author: Jane Doe <[email protected]m>
Date:   Mon Jun 9 14:18:55 2025 +0000

    Merging branch 'crossword'

Basculer vers un tag

Vous pouvez utiliser la commande git checkout pour inspecter un commit tagué. Cela place le dépôt dans un état HEAD détachée — HEAD pointe directement vers un commit plutôt que vers une branche. Les nouveaux commits que vous créez ici n'appartiendront à aucune branche et ne seront accessibles que par leur hash SHA ; ils peuvent donc être perdus dès que vous changez de contexte.

git tag, checking out a tag

git checkout v1.3

Si vous souhaitez continuer à travailler à partir de ce point, créez une branche sur place :

branch from a tag

git checkout -b release-1.3 v1.3

Supprimer des tags

Vous pouvez supprimer un tag local en passant l'option -d et l'identifiant du tag à git tag. Voir l'exemple ci-dessous :

git tag, deleting tags

git tag
v1
v2
v3
git tag -d v1
git tag
v2
v3

La suppression d'un tag localement ne le supprime pas du dépôt distant. Pour supprimer un tag du dépôt distant également, poussez la suppression :

git delete remote tag

git push origin --delete v1

Sujets connexes

• git log — trouver le commit que vous souhaitez tagger.
• git push — publier vos tags vers un dépôt distant.
• git branch — transformer un commit tagué en une branche sur laquelle vous pouvez travailler.

Pratique