Git
Français ▾ Topics ▾ Latest version ▾ git-describe last updated in 2.42.0

NOM

git-describe - Baptiser un objet avec un nom lisible à partir d’une référence disponible

SYNOPSIS

git describe [--all] [--tags] [--contains] [--abbrev=<n>] [<commit-esque>…​]
git describe [--all] [--tags] [--contains] [--abbrev=<n>] --dirty[=<marque>]
git describe <blob>

DESCRIPTION

La commande détecte l’étiquette la plus récente qui est accessible à partir d’un commit. Si l’étiquette indique le commit, seule l’étiquette s’affiche. Dans le cas contraire, elle ajoute au nom de l’étiquette le nombre de validations supplémentaires par dessus l’objet étiqueté et le nom d’objet abrégé de la validation la plus récente. Le résultat est un nom d’objet « lisible par l’homme » qui peut également être utilisé pour identifier le commit pour d’autres commandes git.

Par défaut (sans --all ou --tags) git describe n’affiche que des étiquettes annotées. Pour plus d’informations sur la création d’étiquettes annotées, voir les options -a et -s de git-tag[1].

Si l’objet donné se réfère à un objet blob, il sera décrit comme <commit-esque>:<chemin>, de sorte que le blob peut être trouvé à <chemin> dans le <commit-esque>, qui décrit lui-même le premier commit dans lequel ce blob apparaît dans un parcours inversé de révisions depuis HEAD.

OPTIONS

<commit-esque>…​

Noms d’objet commit-esque à décrire. Par défaut,HEAD si omis.

--dirty[=<marque>]
--broken[=<marque>]

Décrit l’état de l’arbre de travail. Lorsque l’arbre de travail correspond à HEAD, la sortie est la même que « git describe HEAD ». Si l’arbre de travail a la modification locale "-dirty" est ajouté. Si un dépôt est corrompu et Git ne peut pas déterminer s’il y a une modification locale, Git sort en erreur, à moins que --broken soit spécifié, ce qui ajoute le suffixe "-broken" à la place.

--all

Au lieu d’utiliser uniquement les étiquettes annotées, utiliser n’importe quelle référence trouvée dans l’espace de nom`refs/`. Cette option permet de faire correspondre n’importe quelle branche connue, branche de suivi à distance ou étiquette légère.

--tags

Au lieu d’utiliser uniquement les étiquettes annotées, utilisez n’importe quelle étiquette trouvée dans l’espace de noms ‘refs/tags’. Cette option permet de faire correspondre une étiquette légère (non annotée).

--contains

Au lieu de trouver l’étiquette antérieure au commit, trouver l’étiquette qui vient après le commit, et la contient ainsi. Implique automatiquement --tags.

--abbrev=<n>

Au lieu d’utiliser le nombre de chiffres hexadécimaux par défaut (qui varie en fonction du nombre d’objets dans le dépôt avec une valeur par défaut de 7) du nom d’objet abrégé, utiliser <n> chiffres, ou autant de chiffres que nécessaire pour former un nom unique. Un <n> de 0 supprimera le format long, n’affichant que l’étiquette la plus proche.

--candidates=<n>

Au lieu de considérer seulement les 10 étiquettes les plus récentes comme des candidates pour décrire l’entrée commit-esque, considérer jusqu’à <n> candidates. Augmenter <n> au-dessus de 10 prendra un peu plus de temps mais peut produire un résultat plus précis. Un <n> de 0 n’entraînera l’affichage que des correspondances exactes.

--exact-match

Affiche uniquement les correspondances exactes (une étiquette fait directement référence au commit fourni). Ceci est un synonyme de --candidates=0.

--debug

Affiche de nombreuses informations sur la stratégie de recherche utilisée sur la sortie d’erreur. Le nom de l’étiquette sera toujours affiché sur la sortie standard.

--long

Afficher toujours le format long (l’étiquette, le nombre de commits et le nom de validation abrégé) même lorsqu’il correspond à une étiquette. Ceci est utile lorsque vous souhaitez voir des parties du nom d’objet commit dans la sortie de « describe », même lorsque le commit en question se trouve être une version étiquetée. Au lieu de simplement émettre le nom de l’étiquette, il décrira un tel commit comme v1.2-0-gdeadbee (0ème commit depuis l’étiquette v1.2 qui pointe sur l’objet deadbee…​.).

--match <motif>

Ne considérez que les étiquettes correspondant au motif glob(7)' donné, en excluant le préfixe "refs/tags/". Si utilisé avec `--all, prendre également en compte les branches locales et les références de suivi à distance correspondant au motif, en excluant respectivement les préfixes "refs/heads/" et "refs/remotes/" ; les références d’autres types ne sont jamais considérées. Si donné plusieurs fois, une liste de motifs sera accumulée, et les étiquettes correspondant à l’un des motifs seront prises en compte. Utiliser --no-match pour effacer et réinitialiser la liste des motifs.

--exclude <motif>

Ne pas considérer les étiquettes qui correspondent au modèle glob(7)' donné, à l'exclusion du préfixe "refs/tags/". Si utilisé avec `--all, ne pas tenir compte non plus des branches locales et des références de suivi à distance correspondant au motif, à l’exclusion respectivement des préfixes "refs/heads/" et "refs/remotes/" ; les références d’autres types ne sont jamais considérées. Si donné plusieurs fois, une liste de motifs sera accumulée et les étiquettes correspondant à l’un ou l’autre de ces motifs seront exclues. Si combiné avec --match, une étiquette sera prise en compte si elle correspond à au moins un motif --match et ne correspond à aucun des motifs --exclude. Utilisez --no-exclude pour effacer et réinitialiser la liste des motifs.

--always

Afficher les objets commits abrégés en dernier recours.

--first-parent

Ne suivre que le premier commit parent lors de la rencontre d’un commit de fusion. Ceci est utile lorsque vous souhaitez ne pas faire correspondre les étiquettes des branches fusionnées dans l’historique du commit cible.

EXEMPLES

Avec quelque chose comme l’arbre actuel git.git, je reçois :

[torvalds@g5 git]$ git describe parent
v1.0.4-14-g2414721

c’est-à-dire que la tête actuelle de ma branche " mère " est basée sur v1.0.4, mais puisqu’elle a quelques commits en plus, describe a ajouté le nombre de commits supplémentaires (" 14 ") et un nom abrégé pour l’objet commit lui-même (" 2414721 ") à la fin.

Le nombre de commits supplémentaires est le nombre de commits qui seraient affichés par "git log v1.0.4..parent". Le suffixe de hachage est "-g"
abréviation unique pour le commit sommet du parent (qui était 2414721b194453f058079d897d13c4e377f92dc6). La longueur de l’abréviation s’échelonne au fur et à mesure que le dépôt grandit, en utilisant le nombre approximatif d’objets dans le dépôt et un peu de mathématiques autour du paradoxe de l’anniversaire, et la valeur par défaut est de 7. Le préfixe "g" signifie "git" et permet de décrire la version d’un logiciel en fonction du SCM avec lequel le logiciel est géré. Ceci est utile dans un environnement où les gens peuvent utiliser différents SCM.

Faire un git describe sur un nom d’étiquette ne fera qu’afficher le nom de l’étiquette :

[torvalds@g5 git]$ git describe v1.0.4
v1.0.4

Avec --all, la commande peut utiliser des têtes de branches comme références, de sorte que la sortie affiche également le chemin de référence :

[torvalds@g5 git]$ git describe --all --abbrev=4 v1.0.5^2
tags/v1.0.0-21-g975b
[torvalds@g5 git]$ git describe --all --abbrev=4 HEAD^
heads/lt/describe-7-g975b

Avec --abbrev mis à 0, la commande peut être utilisée pour trouver le nom de l’étiquette la plus proche sans suffixe :

[torvalds@g5 git]$ git describe --abbrev=0 v1.0.5^2
tags/v1.0.0

Notez que le suffixe que vous obtiendrez si vous tapez ces commandes aujourd’hui peut être plus long que ce que Linus a vu plus haut quand il a lancé ces commandes, car votre dépôt Git peut avoir de nouveaux commits dont les noms d’objets commencent par 975b qui n’existaient pas à l’époque, et le suffixe "-g975b" seul peut ne pas être suffisant pour désambiguïser ces commits.

STRATÉGIE DE RECHERCHE

Pour chaque commit-esque fourni,git describe cherchera d’abord une étiquette qui marque exactement ce commit. Les étiquettes annotées seront toujours préférées aux étiquettes légères, et les étiquettes avec des dates plus récentes seront toujours préférées aux étiquettes avec des dates plus anciennes. Si une correspondance exacte est trouvée, son nom sera affiché et la recherche s’arrêtera.

Si une correspondance exacte n’a pas été trouvée,git describe reviendra dans l’historique des commits pour localiser un commit ancêtre qui a été étiqueté. L’étiquette de l’ancêtre sera affichée avec une abréviation du SHA1 du commit-esque fourni. Si --first-parent a été spécifié alors la marche ne considérera que le premier parent de chaque commit.

Si plusieurs étiquettes ont été trouvées pendant la marche, alors l’étiquette qui a le moins de commits différents du commit-esque d’entrée sera sélectionnée et affichée. Ici, le moins de commits différents est défini comme le nombre de commits qui seraient affichés par ‘git log étiquette..commit-esque’ soit le plus petit nombre de commits possible.

BOGUES

Les objets d’arbre ainsi que les objets d’étiquette ne pointant pas vers des commits, ne peuvent pas être décrits. Lors de la description des blobs, les étiquettes légères pointant vers les blobs sont ignorées, mais le blob est toujours décrit comme <commit-esque>: <chemin> bien que l’étiquette légère soit plus juste.

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