Übersicht

git describe --tags --dirty --always [--match 'v[0-9]*']

Beschreibung

Diese Seite behandelt git describe aus Versionierungssicht: wie Sie ein Tag-Schema entwerfen, das reproduzierbare Build-Versions-Strings antreibt. Die Ausgabe von git describe wird weit von Build-Systemen (Make, CMake, Cargo, npm-Skripten) verwendet, um einen Versions-String zu erzeugen, der einen Basis-Tag plus Distanz und SHA enthält.

Das empfohlene Muster: Verwenden Sie annotated Semver-Tags wie v1.2.3; Build-Skripte rufen git describe --tags --dirty --always --match 'v[0-9]*' auf; der resultierende String wird über einen generierten Header oder eine Konstante in Binaries eingebettet. Das erzeugt deterministische Versionen, die sowohl das neueste Release als auch unveröffentlichte Arbeit seitdem widerspiegeln.

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 Lightweight zusätzlich zu Annotated Tags.
--dirty[=<mark>]	Hängt einen Marker an, wenn der Tree dirty ist.
--always	Fällt auf abgekürzten SHA zurück, wenn kein Tag erreichbar.
--long	Erzwingt langes Format auch bei einem Tag.
--match <pattern>	Beschränkt auf passende Tags eines Musters (z. B. nightly-* ausschließen).
--exclude <pattern>	Schließt passende Tags aus.
--abbrev=<n>	Länge des abgekürzten SHA.

Beispiele

# Versions-String für einen Build erzeugen
    VERSION=$(git describe --tags --dirty --always --match 'v[0-9]*')
    echo "${VERSION#v}" > VERSION

    # In einem Makefile:
    VERSION := $(shell git describe --tags --dirty --always)
    CFLAGS += -DVERSION="\"$(VERSION)\""

    # In einem package.json prepublish-Skript:
    node -e "p=require('./package.json'); p.version=process.env.VERSION; require('fs').writeFileSync('package.json', JSON.stringify(p,null,2))"

Häufige Fehler

Lightweight Tags zu verwenden, bricht git describe ohne --tags. Release-Candidate- oder Nightly-Tags in Ihrem Match-Muster einzubeziehen erzeugt lärmige Versionen für stabile Builds. Shallow CI-Klone haben möglicherweise gar keine Tags — fetchen Sie sie explizit: git fetch --tags --unshallow.

Verwandte Befehle

git tag, git rev-parse, git for-each-ref, git log