Übersicht

git describe [--tags] [--always] [--dirty] [<commit>]

Beschreibung

Der git describe-Befehl erzeugt einen menschenlesbaren Namen für einen Commit basierend auf dem jüngsten erreichbaren Tag. Die Ausgabe sieht aus wie v1.4.2-13-gabc1234, was bedeutet "13 Commits nach Tag v1.4.2, bei SHA abc1234". Wenn der Commit genau auf einem Tag liegt, wird nur der Tag-Name ausgegeben.

Build-Systeme verwenden git describe, um Versions-Strings in Binaries einzubetten. Mit --dirty enthält die Ausgabe ein -dirty-Suffix, wenn der Working Tree uncommitted Änderungen hat — perfekt zum Markieren von Entwicklungs-Builds.

Im täglichen Einsatz integriert sich git describe eng mit Shell-Aliasen, Editor-Plugins und Continuous Integration. Power-User fügen oft Aliase hinzu, die Flags kombinieren, die sie immer übergeben, oder wickeln den Befehl in Skripte, die Teamkonventionen durchsetzen. Die Ausgabeformatierung kann über Git-Config angepasst werden — Pretty-Formate, Farbschemata und Pager-Verhalten sind alle einstellbar. Wenn etwas schiefgeht, ist der erste Diagnoseschritt üblicherweise, den Befehl erneut mit GIT_TRACE=1 in der Umgebung auszuführen, was die zugrunde liegenden Plumbing-Aufrufe offenlegt. Für ungewöhnliche Situationen öffnet die --help-Ausgabe (git describe --help) die vollständige Manpage mit Details zu jeder Option, einschließlich solcher, die in alltäglichen Workflows selten verwendet werden, aber für Debugging oder Skripting im großen Maßstab essentiell sind.

Zu verstehen, wie git describe mit dem Rest von Gits Datenmodell interagiert — der Objektdatenbank, dem Index, Refs und dem Working Tree — zahlt sich aus. Jeder Befehl operiert auf einer Teilmenge dieser Stücke, und zu wissen, welche er berührt, hilft Ergebnisse vorherzusagen und sich von Fehlern zu erholen. Das Lesen der offiziellen Git-Dokumentation neben praktischer Übung in einem Wegwerf-Repository ist der schnellste Weg, die Nuancen zu verinnerlichen. Die meisten Produktionsprobleme mit Git rühren von einer von drei Ursachen: überraschendem Standardverhalten, partiellen Netzwerkoperationen oder dem Umschreiben bereits geteilter Historie. Ein funktionierendes mentales Modell der Nebenwirkungen von git describe hilft, alle drei zu vermeiden.

Häufige Optionen

Option	Beschreibung
--tags	Verwendet auch lightweight Tags zusätzlich zu annotated.
--always	Fällt auf abgekürzten SHA zurück, falls kein Tag erreichbar.
--dirty[=<mark>]	Hängt einen Marker an, falls der Working Tree dirty ist.
--long	Zeigt immer das lange Format, auch auf einem Tag.
--match <pattern>	Berücksichtigt nur passende Tags eines Glob-Musters.
--abbrev=<n>	Verwendet n Hex-Stellen für den SHA.
--contains	Zeigt den frühesten Tag, der den Commit enthält.

Beispiele

git describe
    # z. B. v2.1.0-3-g1a2b3c4

    git describe --tags --dirty --always
    # Robuster Versions-String für Build-Skripte

    git describe --match 'v[0-9]*'
    # Nur Semver-artige Tags berücksichtigen

    git describe --contains abc123
    # Das erste Release finden, das einen Commit enthält

Häufige Fehler

Wenn Ihr Repo nur lightweight (nicht-annotated) Tags hat, sagt einfaches git describe "fatal: No names found." Verwenden Sie --tags. Shallow Clones haben möglicherweise gar keine erreichbaren Tags — fetchen Sie Tags explizit mit git fetch --tags.

Verwandte Befehle

git tag, git log, git rev-parse, git show