Git
Français ▾ Topics ▾ Latest version ▾ git-tag last updated in 2.46.0

NOM

git-tag - Créer, lister, supprimer ou vérifier un objet étiquette signé avec GPG

SYNOPSIS

git tag [-a | -s | -u <id-clé>] [-f] [-m <msg> | -F <fichier>] [-e]
		[(--trailer <jeton>[(=|:)<valeur>])…​]
	<nom-d-étiquette> [<commit> | <objet>]
git tag -d <nom-d-étiquette>…​
git tag [-n[<num>]] -l [--contains <commit>] [--no-contains <commit>]
	[--points-at <objet>] [--column[=<options>] | --no-column]
	[--create-reflog] [--sort=<clé>] [--format=<format>]
	[--merged <commit>] [--no-merged [<commit>]] [<motif>…​]
git tag -v [--format=<format>] <nom-d-étiquette>…​

DESCRIPTION

Ajouter une référence d’étiquette dans refs/tags/, à moins que -d/-l/-v ne soit donné pour supprimer, lister ou vérifier des étiquettes.

A moins que le -f ne soit donné, l’étiquette indiquée ne doit pas encore exister.

Si l’un des drapeaux -a, -s ou -u<id-clé> est passé, la commande crée un objet « étiquette » et nécessite un message d’étiquetage. À moins que -m <msg> ou -F <fichier> ne soit donné, un éditeur est lancé pour que l’utilisateur puisse taper le message de l’étiquette.

Si -m <msg> ou -F <fichier> ou --trailer <jeton>[=<valeur>]`est donné et que `-a, -s, et -u <id-clé> sont absents, -a est implicite.

Sinon, une référence d’étiquette qui pointe directement sur l’objet donné (c’est-à-dire une étiquette légère) est créée.

Un objet étiquette signé avec GnuPG sera créé lorsque -s ou -u <id-clé> est utilisé. Lorsque -u <id-clé> n’est pas utilisé, l’identité du validateur pour l’utilisateur actuel est utilisée pour trouver la clé GnuPG pour signer. La variable de configuration gpg.program est utilisée pour spécifier un binaire GnuPG personnalisé.

Les objets étiquette (créés avec -a, -s, ou -u) sont appelés étiquettes « annotées » ; ils contiennent une date de création, le nom et l’e-mail de l’étiqueteur, un message d’étiquetage, et une signature GnuPG optionnelle. Alors qu’une étiquette « légère » est simplement un nom pour un objet (généralement un objet commit).

Les étiquettes annotées sont destinées à être diffusées, tandis que les étiquettes légères sont destinées à l’étiquetage d’objets privés ou temporaires. Pour cette raison, certaines commandes git pour nommer les objets (comme git describe) ignorent par défaut les étiquettes légères.

OPTIONS

-a
--annotate

Faire un objet étiquette non signé et annoté

-s
--sign

Faites une étiquette signée GPG, en utilisant la clé de l’adresse électronique par défaut. Le comportement par défaut de signature GPG d’étiquette GPG est contrôlé par la variable de configuration tag.gpgSign si elle existe, ou désactivé sinon. Voir git-config[1].

--no-sign

Surcharge tag.gpgSign qui force toutes les étiquettes à être signées.

-u <id-clé>
--local-user=<id-clé>

Faire une étiquette signée par GPG, en utilisant la clé donnée.

-f
--force

Remplacer une étiquette existante par le nom fourni (au lieu d’échouer)

-d
--delete

Supprimer les étiquettes existantes avec les noms fournis.

-v
--verify

Vérifier la signature GPG des noms d’étiquette donnés.

-n<num>

<num> indique combien de lignes de l’annotation, le cas échéant, sont imprimées lorsque l’on utilise -l. Implique --list.

Par défaut, aucune ligne d’annotation n’est affichée. Si aucun nombre n’est donné à -n, seule la première ligne est affichée. Si l’étiquette n’est pas annotée, le message de commit est affiché à la place.

-l
--list

Lister les étiquettes. Avec l’option <motif>..., par exemple `git tag --list v-* `, ne lister que les étiquettes qui correspondent au(x) motif(s).

L’exécution de "git tag" sans arguments permet également de lister toutes les étiquettes. Le motif est un joker shell (c’est-à-dire que la correspondance est effectuée avec fnmatch(3)). Plusieurs motifs peuvent être donnés ; si l’un d’eux correspond, l’étiquette est affichée.

Cette option est implicitement fournie si une autre option de type liste telle que --contains est fournie. Pour plus de détails, voir la documentation relative à chacune de ces options.

--sort=<clé>

Trier en fonction de la clé donnée. Préfixer par - pour trier par ordre décroissant de la valeur. Vous pouvez utiliser l’option --sort=<clé> plusieurs fois, auquel cas la dernière clé devient la clé primaire. Prend également en charge "version:nom-de-réf" ou "v:nom-de-réf" (les noms d’étiquettes sont traités comme des versions). L’ordre de tri de "version:nom-de-réf" peut également être affecté par la variable de configuration "versionsort.suffixe". Les clés supportées sont les mêmes que celles de git for-each-ref. L’ordre de tri est par défaut la valeur configurée pour la variable tag.sort si elle existe, ou l’ordre lexicographique sinon. Voir git-config[1].

--color[=<quand>]

Respecter toutes les couleurs spécifiées dans l’option --format. Le champ <quand> doit être un des valeur always, never, ou auto (si <quand> est absent, se comporter comme si always était donné).

-i
--ignore-case

Le tri et le filtrage des étiquettes sont non-sensibles à la casse.

--omit-empty

Ne pas afficher de nouvelle ligne après les refs formatés lorsque le format se développe en chaîne vide.

--column[=<options>]
--no-column

Afficher les étiquettes en colonnes. Voir la variable de configuration column.tag pour la syntaxe de l’option. --column et --no-column sans options sont équivalents à always et never respectivement.

Cette option n’est applicable que pour les listes d’étiquettes sans lignes d’annotation.

--contains [<commit>]

Ne répertorier que les étiquettes qui contiennent le commit spécifié (HEAD si non spécifié). Implique --list.

--no-contains [<commit>]

Ne répertorier que les étiquettes qui ne contiennent pas le commit spécifié (HEAD si non spécifié). Implique --list.

--merged [<commit>]

Ne lister que les étiquettes dont les commits sont accessibles à partir du commit spécifié (HEAD si non spécifié).

--no-merged [<commit>]

Ne lister que les étiquettes dont les commits ne sont pas accessibles à partir du commit spécifié (HEAD si non spécifié).

--points-at <objet>

Ne répertorier que les étiquettes de l’objet donné (HEAD si non spécifié). Implique --list.

-m <msg>
--message=<msg>

Utiliser le message d’étiquette fourni (au lieu de le demander). Si plusieurs options -m sont fournies, leurs valeurs sont concaténées comme paragraphes séparés. Implique -a si ni -a, ni -s et ni -u <id-clé> n’est fourni.

-F <fichier>
--file=<fichier>

Prendre le message d’étiquette fourni dans le fichier indiqué. Utiliser - pour lire le message depuis l’entrée standard. Implique -a si ni -a, ni -s et ni -u <id-clé> n’est fourni.

--trailer <jeton>[(=| :)<valeur>]

Spécifier une paire (<jeton>, <valeur>) qui doit être appliquée comme une ligne terminale (par exemple, git tag --trailer "Clé-Personnalisée:valeur" ajoutera la ligne terminale "Clé-Personnelle" au message d’étiquette). Les variables de configuration trailer.* (git-interpret-trailers[1]) peuvent être utilisées pour définir si une ligne terminale dupliquée est omise, ou où chaque ligne terminale apparaîtrait dans la série de lignes terminales, et d’autres détails. Les lignes terminales peuvent être extraites dans git tag --list, en utilisant --format="%(trailers)".

-e
--edit

Le message tiré d’un fichier avec -F, ou de la ligne de commande avec -m est généralement utilisé sans modification. Cette option permet d’éditer au passage le message tiré de ces sources.

--cleanup=<mode>

Cette option définit la manière dont le message de l’étiquette est nettoyé. Le <mode> peut être un verbatim, whitespace ou strip. Le mode strip est le mode par défaut. Le mode verbatim ne modifie pas du tout le message, whitespace supprime uniquement les lignes vides de début et de fin et strip supprime à la fois les espaces et les commentaires.

--create-reflog

Créer un reflog pour l’étiquette. Pour activer globalement les reflogs pour les étiquettes, voir core.logAllRefUpdates dans git-config[1]. La forme inversée --no-create-reflog ne fait que remplacer une précédente --create-reflog, mais n’annule pas actuellement le paramètre de core.logAllRefUpdates.

--format=<format>

Une chaîne qui interpole %(fieldname) à partir d’une référence d’étiquette affichée et de l’objet qu’il pointe. Le format est le même que celui de git-for-each-ref[1]. Lorsqu’elle n’est pas spécifiée, la valeur par défaut est %(refname:strip=2).

<nom-d-étiquette>

Le nom de l’étiquette à créer, supprimer ou décrire. Le nouveau nom de l’étiquette doit passer tous les contrôles définis par git-check-ref-format[1]. Certains de ces contrôles peuvent restreindre les caractères autorisés dans un nom d’étiquette.

<commit>
<objet>

L’objet auquel la nouvelle étiquette fera référence, généralement un commit. La valeur par défaut est HEAD.

CONFIGURATION

Par défaut, git tag en mode signer-par-défaut (-s) utilisera votre identité de validateur (de la forme Votre Nom <votre@adresse.courriel>) pour trouver une clé. Si vous souhaitez utiliser une clé par défaut différente, vous pouvez la spécifier dans la configuration du dépôt comme suit :

[user]
    signingKey = <id-clé-gpg>

pager.tag n’est respecté que lors de l’énumération des étiquettes, c’est-à-dire lorsque le -l est utilisé ou sous-entendu. La valeur par défaut est l’utilisation d’un pager. Voir git-config[1].

DISCUSSION

À propos du ré-étiquetage

Que devez-vous faire lorsque vous marquez un mauvais commit et que vous souhaitez ré-étiqueter ?

Si vous n’avez jamais rien pousser à l’extérieur, il suffit de le re-étiqueter. Utilisez "-f" pour remplacer l’ancienne étiquette. Et c’est fini.

Mais si vous avez poussé des choses (ou si d’autres ont pu lire directement votre dépôt), alors d’autres auront déjà vu l’ancienne étiquette. Dans ce cas, vous pouvez faire l’une des deux choses suivantes :

  1. Le bon comportement. Admettez juste que vous avez foiré, et utilisez un autre nom. D’autres ont déjà vu un nom d’étiquette, et si vous gardez le même nom, vous pouvez vous retrouver dans la situation où deux personnes ont toutes deux une "version X", mais en fait elles ont des "X" différents. Il suffit donc de baptiser le bon commit "X.1" et cela règle l’affaire.

  2. Le comportement débile. Vous voulez vraiment appeler la nouvelle version "X" aussi, "même si" d’autres ont déjà vu l’ancienne. Alors utilisez à nouveau l’étiquette "git tag -f", comme si vous n’aviez pas déjà publié l’ancienne version.

Cependant, Git ne change pas (et ne devrait pas changer) les étiquettes dans le dos les utilisateurs. Ainsi, si quelqu’un a déjà l’ancienne étiquette, le fait de faire un git pull sur votre arbre ne devrait simplement pas l’obliger à écraser l’ancienne.

Si quelqu’un a reçu de vous une étiquette de publication, vous ne pouvez simplement pas la changer chez lui en mettant à jour votre propre étiquette. Il s’agit d’un problème de sécurité important, car les gens DOIVENT pouvoir faire confiance en leur nom d’étiquette. Si vous voulez vraiment faire une folie, vous devez simplement le reconnaître et dire aux gens que vous avez fait une erreur. Vous pouvez le faire en faisant une annonce très publique disant :

Ok, je me suis trompé, et j'ai sorti une version antérieure étiquetée X. J'ai
depuis corrigé quelque chose, et j'ai à nouveau marqué l'arbre *corrigé* comme X.

Si vous vous êtes trompé d'étiquette et que vous voulez la nouvelle, veuillez supprimer
l'ancienne et aller chercher la nouvelle en faisant :

	git tag -d X
	git fetch origin tag X

pour obtenir mon étiquette mise à jour.

Vous pouvez vérifier quelle étiquette vous avez en faisant

	git rev-parse X

qui devrait renvoyer 0123456789abcdef... si vous avez la nouvelle version.

Désolé pour le désagrément.

Cela vous semble-t-il un peu compliqué ? Ça devrait l’être. Il n’y a aucun moyen qui soit correct pour simplement "réparer" cela automatiquement. Les gens doivent savoir que leurs étiquettes ont peut-être été modifiées.

Sur le suivi automatique

Si vous suivez l’arbre de quelqu’un d’autre, vous utilisez très probablement des branches de suivi à distance (par exemple, refs/remotes/origin/master). Vous voulez généralement les étiquettes de l’autre dépôt.

D’autre part, si vous récupérez parce que vous voudriez une seule fois une fusion de quelqu’un d’autre, vous ne voulez généralement pas obtenir d’étiquettes à partir de là. Cela se produit plus souvent pour les personnes proches du niveau supérieur, mais pas seulement pour elles. Les simples mortels qui se tirent les uns des autres ne veulent pas nécessairement obtenir automatiquement des étiquettes de point d’ancrage privés de l’autre personne.

Souvent, les messages "veuillez tirer" sur la liste de diffusion ne fournissent que deux informations : une URL de dépôt et un nom de branche ; ils sont conçus pour être facilement coupés-collés à la fin d’une ligne de commande "git fetch" :

Linus, veuillez tirer de

	git://git..../proj.git master

pour récupérer les mises à jour suivantes…

devient :

$ git pull git://git..../proj.git master

Dans un tel cas, vous ne voulez pas suivre automatiquement les étiquettes de l’autre personne.

Un aspect important de Git est sa nature distribuée, ce qui signifie en grande partie qu’il n’y a pas de manière inhérente d'"amont" ou d'"aval" dans le système. À première vue, l’exemple ci-dessus pourrait sembler indiquer que l’espace de noms des étiquettes appartient à l’échelon supérieur des personnes et que les étiquettes ne circulent que vers le bas, mais ce n’est pas le cas. Il montre seulement que le schéma d’utilisation détermine qui s’intéresse à quelles étiquettes.

Un tirage pour une fois est le signe qu’un historique de commit franchit maintenant la frontière entre un cercle de personnes (par exemple « les personnes qui sont principalement intéressées par la partie réseau du noyau ») qui peuvent avoir leur propre ensemble d’étiquettes (par exemple "c’est la troisième version candidate du groupe réseau à être proposée pour la consommation générale avec la version 2.6.21") et un autre cercle de personnes (par exemple "les personnes qui intègrent diverses améliorations du sous-système"). Ces derniers ne sont généralement pas intéressés par les étiquettes détaillées utilisées en interne dans le premier groupe (c’est ce que signifie "interne"). C’est pourquoi il est souhaitable de ne pas suivre automatiquement les étiquettes dans ce cas.

Il se peut très bien que les personnes travaillant sur le réseau veuillent échanger les étiquettes internes à leur groupe, mais dans ce flux de travail, elles suivent très probablement les progrès des autres en ayant des branches de suivi à distance. Là encore, l’heuristique consistant à suivre automatiquement ces étiquettes est une bonne chose.

Sur l’antidatage d’étiquettes

Si vous avez importé des modifications d’un autre VCS et que vous souhaitez ajouter des étiquettes pour les versions majeures de votre travail, il est utile de pouvoir spécifier la date à intégrer dans l’objet étiquette ; ces données dans l’objet étiquette affectent, par exemple, l’ordre des étiquettes dans l’interface gitweb.

Pour définir la date utilisée dans les futurs objets étiquette, définissez la variable d’environnement GIT_COMMITTER_DATE (voir la discussion ultérieure des valeurs possibles ; la forme la plus courante est "YYYY-MM-DD HH:MM").

Par exemple :

$ GIT_COMMITTER_DATE="2006-10-02 10:31" git tag -s v1.0.1

FORMATS DE DATE

Les variables d’environnement GIT_AUTHOR_DATE et GIT_COMMITTER_DATE supportent les formats de date suivants :

Format interne de Git

Il est de la forme <horodatage-unix> <décalage-de-fuseau-horaire>, où <horodatage-unix> est un nombre de secondes depuis l’époque UNIX. <décalage-de-fuseau-horaire> est un décalage positif ou négative par rapport à UTC. Par exemple, CET (qui est en avance d’une heure sur UTC) est +0100.

RFC 2822

Le standard de format de date tel que décrit par la RFC 2822, par exemple Thu, 07 Apr 2005 22:13:13 +0200.

ISO 8601

Les heures et les dates sont spécifiées par le standard ISO 8601, par exemple 2005-04-07T22:13:13. L’analyseur accepte aussi un espace au lieu du caractère T. Les parties fractionnelles d’une seconde seront ignorées, par exemple, 2005-04-07T22:13:13.019 sera considéré comme étant 2005-04-07T22:13:13.

Note
 De plus, la partie date est acceptée dans les formats suivants : AAAA.MM.JJ, MM/JJ/AAAA et JJ.MM.AAAA.

FICHIERS

$GIT_DIR/TAG_EDITMSG

Ce fichier contient le message de l’étiquette annotée en cours. Si git tag sort à cause d’une erreur avant de créer une étiquette annotée, alors le message de l’étiquette annotée fourni par l’utilisateur dans une session d’éditeur sera disponible dans ce fichier, mais sera écrasé par l’invocation suivante de git tag.

NOTES

Lorsque vous combinez plusieurs filtres --contains et --no-contains, seules les références qui contiennent au moins un des commits --contains et ne contiennent aucun des commits --no-contains sont affichées.

Lorsque vous combinez plusieurs filtres --merged et --no-merged, seules les références qui sont accessibles depuis au moins un des commits --merged et depuis aucun des commits --no-merged sont affichées.

VOIR AUSSI

git-check-ref-format[1]. git-config[1].

GIT

Fait partie de la suite git[1]

TRADUCTION

Cette page de manuel a été traduite par Jean-Noël Avila <jn.avila AT free DOT fr> et les membres du projet git-manpages-l10n. Veuillez signaler toute erreur de traduction par un rapport de bogue sur le site https://github.com/jnavila/git-manpages-l10n .

scroll-to-top