Git
Chapters ▾ 2nd Edition

2.6 Les bases de Git - Étiquetage

Étiquetage

À l’instar de la plupart des VCS, Git donne la possibilité d’étiqueter un certain état dans l’historique comme important. Généralement, les gens utilisent cette fonctionnalité pour marquer les états de publication (v1.0 et ainsi de suite). Dans cette section, nous apprendrons comment lister les différentes étiquettes (tag en anglais), comment créer de nouvelles étiquettes et les différents types d’étiquettes.

Lister vos étiquettes

Lister les étiquettes existantes dans Git est très simple. Tapez juste git tag :

$ git tag
v0.1
v1.3

Cette commande liste les étiquettes dans l’ordre alphabétique. L’ordre dans lequel elles apparaissent n’a aucun rapport avec l’historique.

Vous pouvez aussi rechercher les étiquettes correspondant à un motif particulier. Par exemple, le dépôt des sources de Git contient plus de 500 étiquettes. Si vous souhaitez ne visualiser que les séries 1.8.5, vous pouvez lancer ceci :

$ git tag -l 'v1.8.5*'
v1.8.5
v1.8.5-rc0
v1.8.5-rc1
v1.8.5-rc2
v1.8.5-rc3
v1.8.5.1
v1.8.5.2
v1.8.5.3
v1.8.5.4
v1.8.5.5
Note
Lister les étiquettes avec des jokers nécessite les options -l ou --list

Si vous voulez juste la liste complète des étiquettes, la commande git tag considère implicitement que vous souhaitez une liste et elle la fournit ; l’utilisation de -l ou --list est optionnelle dans ce cas.

Cependant, si vous fournissez un motif joker pour filtrer les d’étiquettes, l’utilisation de -l ou --list est obligatoire.

Créer des étiquettes

Git utilise deux types principaux d’étiquettes : légères et annotées.

Une étiquette légère ressemble beaucoup à une branche qui ne change pas, c’est juste un pointeur sur un commit spécifique.

Les étiquettes annotées, par contre, sont stockées en tant qu’objets à part entière dans la base de données de Git. Elles ont une somme de contrôle, contiennent le nom et l’adresse e-mail du créateur, la date, un message d’étiquetage et peuvent être signées et vérifiées avec GNU Privacy Guard (GPG). Il est généralement recommandé de créer des étiquettes annotées pour générer toute cette information mais si l’étiquette doit rester temporaire ou l’information supplémentaire n’est pas désirée, les étiquettes légères peuvent suffire.

Les étiquettes annotées

Créer des étiquettes annotées est simple avec Git. Le plus simple est de spécifier l’option -a à la commande tag :

$ git tag -a v1.4 -m 'ma version 1.4'
$ git tag
v0.1
v1.3
v1.4

L’option -m permet de spécifier le message d’étiquetage qui sera stocké avec l’étiquette. Si vous ne spécifiez pas de message en ligne pour une étiquette annotée, Git lance votre éditeur pour pouvoir le saisir.

Vous pouvez visualiser les données de l’étiquette à côté du commit qui a été marqué en utilisant la commande git show :

$ git show v1.4
tag v1.4
Tagger: Ben Straub <ben@straub.cc>
Date:   Sat May 3 20:19:12 2014 -0700

ma version 1.4

commit ca82a6dff817ec66f44342007202690a93763949
Author: Scott Chacon <schacon@gee-mail.com>
Date:   Mon Mar 17 21:52:11 2008 -0700

    changed the version number

Cette commande affiche le nom du créateur, la date de création de l’étiquette et le message d’annotation avant de montrer effectivement l’information de validation.

Les étiquettes légères

Une autre manière d’étiqueter les commits est d’utiliser les étiquettes légères. Celles-ci se réduisent à stocker la somme de contrôle d’un commit dans un fichier, aucune autre information n’est conservée. Pour créer une étiquette légère, il suffit de n’utiliser aucune des options -a, -s ou -m :

$ git tag v1.4-lg
$ git tag
v0.1
v1.3
v1.4
v1.4-lg
v1.5

Cette fois-ci, en lançant git show sur l’étiquette, on ne voit plus aucune information complémentaire. La commande ne montre que l’information de validation :

$ git show v1.4-lg
commit ca82a6dff817ec66f44342007202690a93763949
Author: Scott Chacon <schacon@gee-mail.com>
Date:   Mon Mar 17 21:52:11 2008 -0700

    changed the version number

Étiqueter après coup

Vous pouvez aussi étiqueter des commits plus anciens. Supposons que l’historique des commits ressemble à ceci :

$ git log --pretty=oneline
15027957951b64cf874c3557a0f3547bd83b3ff6 Fusion branche 'experimental'
a6b4c97498bd301d84096da251c98a07c7723e65 Début de l'écriture support
0d52aaab4479697da7686c15f77a3d64d9165190 Un truc de plus
6d52a271eda8725415634dd79daabbc4d9b6008e Fusion branche 'experimental'
0b7434d86859cc7b8c3d5e1dddfed66ff742fcbc ajout d'une fonction de validatn
4682c3261057305bdd616e23b64b0857d832627b ajout fichier afaire
166ae0c4d3f420721acbb115cc33848dfcc2121a début de l'ecriture support
9fceb02d0ae598e95dc970b74767f19372d61af8 mise à jour rakefile
964f16d36dfccde844893cac5b347e7b3d44abbc validation afaire
8a5cbc430f1a9c3d00faaeffd07798508422908a mise à jour lisezmoi

Maintenant, supposons que vous avez oublié d’étiqueter le projet à la version v1.2 qui correspondait au commit « mise à jour rakefile ». Vous pouvez toujours le faire après l’évènement. Pour étiqueter ce commit, vous spécifiez la somme de contrôle du commit (ou une partie) en fin de commande :

$ git tag -a v1.2 9fceb02

Le commit a été étiqueté :

$ git tag
v0.1
v1.2
v1.3
v1.4
v1.4-lg
v1.5

$ git show v1.2
tag v1.2
Tagger: Scott Chacon <schacon@gee-mail.com>
Date:   Mon Feb 9 15:32:16 2009 -0800

version 1.2
commit 9fceb02d0ae598e95dc970b74767f19372d61af8
Author: Magnus Chacon <mchacon@gee-mail.com>
Date:   Sun Apr 27 20:43:35 2008 -0700

    updated rakefile
...

Partager les étiquettes

Par défaut, la commande git push ne transfère pas les étiquettes vers les serveurs distants. Il faut explicitement pousser les étiquettes après les avoir créées localement. Ce processus s’apparente à pousser des branches distantes — vous pouvez lancer git push origin [nom-du-tag].

$ git push origin v1.5
Décompte des objets: 14, fait.
Delta compression using up to 8 threads.
Compression des objets: 100% (12/12), fait.
Écriture des objets: 100% (14/14), 2.05KiB | 0 bytes/s, fait.
Total 14 (delta 3), reused 0 (delta 0)
To git@github.com:schacon/simplegit.git
 * [new tag]         v1.5 -> v1.5

Si vous avez de nombreuses étiquettes que vous souhaitez pousser en une fois, vous pouvez aussi utiliser l’option --tags avec la commande git push. Ceci transférera toutes les nouvelles étiquettes vers le serveur distant.

$ git push origin --tags
Décompte des objets: 1, fait.
Écriture des objets: 100% (1/1), 160 bytes | 0 bytes/s, fait.
Total 1 (delta 0), reused 0 (delta 0)
To git@github.com:schacon/simplegit.git
 * [new tag]         v1.4 -> v1.4
 * [new tag]         v1.4-lg -> v1.4-lg

À présent, lorsqu’une autre personne clone ou tire depuis votre dépôt, elle obtient aussi les étiquettes.

Note
git push pousse les deux types d’étiquettes

git push <distant> --tags pousse à la fois les étiquettes légères et annotées. Il n’y a actuellement aucune option pour pousser seulement les étiquettes légères, mais si vous utilisez git push <distant> --follow-tags, seules les étiquettes annotées seront poussées sur le serveur distant.

Supprimer les étiquettes

Pour supprimer une étiquette de votre dépôt local, vous pouvez utiliser git tag -d <nom-d-etiquette>. Par example, nous pourrions supprimer notre étiquette légère ci-dessus, comme ceci :

$ git tag -d v1.4-lw
Deleted tag 'v1.4-lw' (was e7d5add)

Notez que ceci ne supprime pas l’étiquette sur aucun serveur distant. Il y a deux méthodes communes pour supprimer une étiquette d’un serveur distant.

La première est git push <distant> :refs/tags/<nom-d-etiquette>:

$ git push origin :refs/tags/v1.4-lw
To /git@github.com:schacon/simplegit.git
 - [deleted]         v1.4-lw

Ceci s’interprète comme une valeur nulle devant les deux points qui est envoyée sur le nom d’étiquette distante, ce qui l’efface.

La seconde manière (et la plus intuitive) pour supprimer une étiquette distante utilise l’option --delete :

$ git push origin --delete <nom-d-etiquette>

Extraire une étiquette

Si vous souhaitez voir les versions de fichiers qu’une étiquette pointe, vous pouvez faire un git checkout de cette étiquette, bien que cela positionne votre dépôt dans un état « HEAD détachée », ce qui a quelques effets de bords malheureux :

git checkout v2.29.2
Note : basculement sur 'v2.29.2'.

Vous êtes dans l'état « HEAD détachée ». Vous pouvez visiter, faire des modifications
expérimentales et les valider. Il vous suffit de faire un autre basculement pour
abandonner les commits que vous faites dans cet état sans impacter les autres branches

Si vous voulez créer une nouvelle branche pour conserver les commits que vous créez,
il vous suffit d'utiliser l'option -c de la commande switch comme ceci :

  git switch -c <nom-de-la-nouvelle-branche>

Ou annuler cette opération avec :

  git switch -

Désactivez ce conseil en renseignant la variable de configuration advice.detachedHead à false

HEAD est maintenant sur 898f80736c Git 2.29.2

$ git checkout v2.29.1
La position précédente de HEAD était sur 898f80736c Git 2.29.2
HEAD est maintenant sur b927c80531 Git 2.29.1

Dans l’état « HEAD détachée », si vous modifiez puis créez un commit, l’étiquette restera identique, mais votre nouveau commit n’appartiendra à aucune branche et sera non joignable, à part avec son empreinte de commit exacte. Ainsi, si vous avez besoin de faire des modifications — disons que vous corrigez un bogue d’une ancienne version, par exemple — vous voudrez généralement créer une branche :

$ git checkout -b v2.9.X
Basculement sur la nouvelle branche 'v2.9.X'

Si vous faites ceci et que vous faites un commit, votre branche V2.9.X sera légèrement différente de votre étiquette v2.9.1 puisqu’elle aura avancé avec les modifications que vous y aurez intégrées, donc faites attention.