git describe

Inspection et comparaison

Donner à un commit un nom lisible basé sur le tag le plus proche

La commande 'git describe' nomme un commit d’après le tag le plus proche qu’il atteint : le tag lui-même si le commit est tagué, sinon tag-N-gHASH (N commits après le tag, puis le hash abrégé). Les scripts de build l’utilisent pour marquer chaque build d’une version. Par défaut, seuls les tags annotés sont utilisés.

Synopsis

git describe [--tags] [--always] [--dirty] [--abbrev=<n>] [<commit-ish>...]
[ ] facultatif| ou<arg> valeur à remplacer... répétable--flag option

Options

Cliquez sur une option pour la déplier

Débutant (3)

Utiliser n’importe quel tag, y compris les tags légers, pas seulement les annotés.

Si nécessaireQuand votre projet utilise des tags légers

Exemple

git describe --tags

Afficher le hash abrégé du commit quand aucun tag ne peut le décrire.

RecommandéNe jamais échouer : afficher le hash court quand aucun tag n’est trouvé

Exemple

git describe --always

Ajouter -dirty quand le répertoire de travail a des modifications non committées.

RecommandéSignaler les builds faits avec des modifications non committées

Exemple

git describe --dirty

Choisir la bonne option

Lire un nom produit par describe

v1.0-2-g1a2b3c4

CommandeSignification
v1.0Le tag le plus proche
2Commits depuis ce tag
g1a2b3c4« g » pour git + le hash abrégé
-dirtyModifications non committées (avec --dirty)

Exemples

Décrire HEAD

git describe

v1.0-2-g1a2b3c4 : deux commits après v1.0.

Inclure les tags légers

git describe --tags

Prendre aussi en compte les tags créés sans -a.

Ne jamais échouer

git describe --always --dirty

Le hash s’il n’y a pas de tag, -dirty s’il y a des modifications locales.

Exemples de workflows

1
git describe --tags --always --dirty

Calculer la chaîne de version

2
echo "$(git describe --tags --always)" > version.txt

L’écrire dans le build

Dépannage

fatal: No names found, cannot describe anything.

Cause : Le dépôt n’a pas de tag

Créez-en un (git tag -a v0.1 -m ...) ou utilisez --always

fatal: No annotated tags can describe ...

Cause : Il n’existe que des tags légers

Utilisez --tags, ou recréez le tag avec -a

Astuces et pièges

Bonnes pratiques

  • ✓Utilisez des tags annotés pour les versions, pour que describe marche sans --tags.
  • ✓Utilisez --always dans les scripts pour qu’ils n’échouent jamais.

Erreurs fréquentes

  • ✗Obtenir "No names found" parce que le projet n’a que des tags légers — ajoutez --tags.
  • ✗Lire le g de -g1a2b3c4 comme faisant partie du hash : il signifie juste « git ».

FAQ

A:

Il prend le tag avec le moins de commits entre lui et le commit décrit.