English ▾ Themen ▾ Neueste Version ▾ git-describe zuletzt aktualisiert in 2.42.0

NAME

git-describe - Gib einem Objekt einen menschenlesbaren Namen basierend auf einem verfügbaren Ref

SYNOPSIS

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

BESCHREIBUNG

Der Befehl findet das aktuellste Tag, das von einem Commit erreichbar ist. Wenn das Tag auf den Commit zeigt, wird nur das Tag angezeigt. Andernfalls wird der Tag-Name mit der Anzahl zusätzlicher Commits über dem getaggten Objekt und dem abgekürzten Objektnamen des aktuellsten Commits ergänzt. Das Ergebnis ist ein "menschenlesbarer" Objektname, der auch verwendet werden kann, um den Commit für andere Git-Befehle zu identifizieren.

Standardmäßig (ohne --all oder --tags) zeigt git describe nur annotierte Tags an. Weitere Informationen zur Erstellung annotierter Tags finden Sie in den Optionen -a und -s von git-tag[1].

Wenn das angegebene Objekt sich auf ein Blob bezieht, wird es als <commit-ish>:<pfad> beschrieben, sodass das Blob unter <pfad> im <commit-ish> gefunden werden kann, welches selbst den ersten Commit beschreibt, in dem dieses Blob in einem umgekehrten Revisions-Walk von HEAD auftritt.

OPTIONEN

<commit-ish>…​

Commit-ish-Objektnamen, die beschrieben werden sollen. Standardmäßig HEAD, wenn weggelassen.

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

Beschreiben Sie den Zustand des Arbeitsbaums. Wenn der Arbeitsbaum mit HEAD übereinstimmt, ist die Ausgabe dieselbe wie bei "git describe HEAD". Wenn der Arbeitsbaum lokale Modifikationen aufweist, wird "-dirty" angehängt. Wenn ein Repository beschädigt ist und Git nicht feststellen kann, ob lokale Modifikationen vorhanden sind, wird Git mit einem Fehler aussteigen, es sei denn, es wird '--broken' angegeben, das stattdessen das Suffix "-broken" anhängt.

--all

Anstatt nur die annotierten Tags zu verwenden, wird jeder Ref im Namespace refs/ verwendet. Diese Option ermöglicht die Übereinstimmung mit jedem bekannten Branch, Remote-Tracking-Branch oder Lightweight-Tag.

--tags

Anstatt nur die annotierten Tags zu verwenden, wird jedes Tag im Namespace refs/tags verwendet. Diese Option ermöglicht die Übereinstimmung mit einem Lightweight-Tag (nicht-annotiert).

--contains

Anstatt das Tag zu finden, das dem Commit vorausgeht, wird das Tag gefunden, das nach dem Commit kommt und ihn somit enthält. Dies impliziert automatisch --tags.

--abbrev=<n>

Anstatt die Standardanzahl von hexadezimalen Ziffern (die je nach Anzahl der Objekte im Repository variiert, standardmäßig 7) des abgekürzten Objektnamens zu verwenden, werden <n> Ziffern verwendet oder so viele Ziffern wie nötig, um einen eindeutigen Objektnamen zu bilden. Ein <n> von 0 unterdrückt das Langformat und zeigt nur das nächstgelegene Tag an.

--candidates=<n>

Anstatt nur die 10 aktuellsten Tags als Kandidaten zur Beschreibung des Eingabe-Commit-ish zu betrachten, werden bis zu <n> Kandidaten betrachtet. Eine Erhöhung von <n> über 10 hinaus dauert geringfügig länger, kann aber zu einem genaueren Ergebnis führen. Ein <n> von 0 führt dazu, dass nur exakte Übereinstimmungen ausgegeben werden.

--exact-match

Gibt nur exakte Übereinstimmungen aus (ein Tag verweist direkt auf den übergebenen Commit). Dies ist ein Synonym für --candidates=0.

--debug

Zeigt ausführliche Informationen über die verwendete Suchstrategie auf Standardfehler an. Der Tag-Name wird weiterhin auf Standardausgabe ausgegeben.

--long

Gibt immer das Langformat aus (das Tag, die Anzahl der Commits und den abgekürzten Commit-Namen), auch wenn es mit einem Tag übereinstimmt. Dies ist nützlich, wenn Sie Teile des Commit-Objektnamens in der "describe"-Ausgabe sehen möchten, auch wenn der betreffende Commit eine getaggte Version ist. Anstatt nur den Tag-Namen auszugeben, wird ein solcher Commit als v1.2-0-gdeadbee beschrieben (0. Commit seit Tag v1.2, der auf das Objekt deadbee zeigt...).

--match <muster>

Berücksichtigt nur Tags, die dem angegebenen glob(7)-Muster entsprechen, wobei der Präfix "refs/tags/" ausgeschlossen wird. Bei Verwendung von --all werden auch lokale Branches und Remote-Tracking-Referenzen berücksichtigt, die dem Muster entsprechen, wobei die Präfixe "refs/heads/" bzw. "refs/remotes/" ausgeschlossen werden; Referenzen anderer Typen werden nie berücksichtigt. Wenn dies mehrmals angegeben wird, wird eine Liste von Mustern angehäuft, und Tags, die einem der Muster entsprechen, werden berücksichtigt. Verwenden Sie --no-match, um die Liste der Muster zu löschen und zurückzusetzen.

--exclude <muster>

Berücksichtigt keine Tags, die dem angegebenen glob(7)-Muster entsprechen, wobei der Präfix "refs/tags/" ausgeschlossen wird. Bei Verwendung von --all werden auch keine lokalen Branches und Remote-Tracking-Referenzen berücksichtigt, die dem Muster entsprechen, wobei die Präfixe "refs/heads/" bzw. "refs/remotes/" ausgeschlossen werden; Referenzen anderer Typen werden nie berücksichtigt. Wenn dies mehrmals angegeben wird, wird eine Liste von Mustern angehäuft und Tags, die einem der Muster entsprechen, werden ausgeschlossen. In Kombination mit --match wird ein Tag berücksichtigt, wenn es mindestens einem --match-Muster entspricht und keinem der --exclude-Muster entspricht. Verwenden Sie --no-exclude, um die Liste der Muster zu löschen und zurückzusetzen.

--always

Zeigt als Fallback einen eindeutig abgekürzten Commit-Objektnamen an.

--first-parent

Folgt nur dem ersten Eltern-Commit bei einem Merge-Commit. Dies ist nützlich, wenn Sie keine Tags auf Branches abgleichen möchten, die in der Historie des Ziel-Commits gemerged wurden.

BEISPIELE

Mit etwas wie dem aktuellen Baum von git.git erhalte ich

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

d.h. der aktuelle Kopf meines "Eltern"-Branches basiert auf v1.0.4, aber da er einige Commits darauf hat, hat describe die Anzahl zusätzlicher Commits ("14") und einen abgekürzten Objektnamen für den Commit selbst ("2414721") am Ende hinzugefügt.

Die Anzahl der zusätzlichen Commits ist die Anzahl der Commits, die von "git log v1.0.4..parent" angezeigt würden. Der Hash-Suffix ist "-g" + eine eindeutige Abkürzung für die Spitze des Parents (welche 2414721b194453f058079d897d13c4e377f92dc6 war). Die Länge der Abkürzung skaliert mit wachsendem Repository, verwendet die ungefähre Anzahl von Objekten im Repository und etwas Mathematik rund um das Geburtstagsparadoxon und hat standardmäßig ein Minimum von 7. Das Präfix "g" steht für "git" und wird verwendet, um die Version einer Software zu beschreiben, die von der SCM verwaltet wird, mit der die Software verwaltet wird. Dies ist nützlich in einer Umgebung, in der Menschen verschiedene SCMs verwenden können.

Wenn Sie git describe für einen Tag-Namen ausführen, wird nur der Tag-Name angezeigt

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

Mit --all kann der Befehl Branch-Köpfe als Referenzen verwenden, sodass die Ausgabe auch den Referenzpfad anzeigt

[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

Mit --abbrev auf 0 gesetzt, kann der Befehl verwendet werden, um den nächstgelegenen Tag-Namen ohne Suffix zu finden

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

Beachten Sie, dass der Suffix, den Sie heute erhalten, wenn Sie diese Befehle eingeben, länger sein kann als das, was Linus oben sah, als er diese Befehle ausführte, da Ihr Git-Repository möglicherweise neue Commits hat, deren Objektnamen mit 975b beginnen und die damals nicht existierten, und der Suffix "-g975b" allein möglicherweise nicht ausreicht, um diese Commits zu disambiguieren.

SUCHSTRATEGIE

Für jeden übergebenen Commit-ish sucht git describe zuerst nach einem Tag, das genau diesen Commit taggt. Annotierte Tags werden immer leichten Tags vorgezogen, und Tags mit neueren Daten werden immer Tags mit älteren Daten vorgezogen. Wenn eine exakte Übereinstimmung gefunden wird, wird ihr Name ausgegeben und die Suche beendet.

Wenn keine exakte Übereinstimmung gefunden wurde, durchläuft git describe die Commit-Historie rückwärts, um einen Vorgänger-Commit zu lokalisieren, der getaggt wurde. Das Tag des Vorgängers wird zusammen mit einer Abkürzung der SHA-1 des Eingabe-Commit-ish ausgegeben. Wenn --first-parent angegeben wurde, berücksichtigt der Walk nur den ersten Elternteil jedes Commits.

Wenn während des Walks mehrere Tags gefunden wurden, wird das Tag ausgewählt und ausgegeben, das die wenigsten Commits vom Eingabe-Commit-ish unterscheidet. Wenigste unterschiedliche Commits ist hier definiert als die Anzahl der Commits, die von git log tag..input angezeigt würden und die kleinstmögliche Anzahl von Commits darstellt.

BUGS

Tree-Objekte sowie Tag-Objekte, die nicht auf Commits zeigen, können nicht beschrieben werden. Beim Beschreiben von Blobs werden die leichten Tags, die auf Blobs zeigen, ignoriert, aber der Blob wird trotzdem als <commit-ish>:<pfad> beschrieben, obwohl der leichte Tag vorteilhafter ist.

GIT

Teil der git[1] Suite