English ▾ Themen ▾ Neueste Version ▾ git-tag zuletzt aktualisiert in 2.52.0

NAME

git-tag - Tags erstellen, auflisten, löschen oder überprüfen

SYNOPSIS

git tag [-a | -s | -u <key-id>] [-f] [-m <msg> | -F <file>] [-e]
	[(--trailer <token>[(=|:)<value>])…​]
	<tagname> [<commit> | <object>]
git tag -d <tagname>…​
git tag [-n[<num>]] -l [--contains <commit>] [--no-contains <commit>]
	[--points-at <object>] [--column[=<options>] | --no-column]
	[--create-reflog] [--sort=<key>] [--format=<format>]
	[--merged <commit>] [--no-merged <commit>] [<pattern>…​]
git tag -v [--format=<format>] <tagname>…​

BESCHREIBUNG

Fügt einen Tag-Referenz in refs/tags/ hinzu, es sei denn, -d/-l/-v wird angegeben, um Tags zu löschen, aufzulisten oder zu überprüfen.

Wenn -f nicht angegeben wird, darf der benannte Tag noch nicht existieren.

Wenn eine der Optionen -a, -s oder -u <key-id> übergeben wird, erstellt der Befehl ein Tag-Objekt und erfordert eine Tag-Nachricht. Wenn nicht -m <msg> oder -F <file> angegeben wird, wird ein Editor gestartet, damit der Benutzer die Tag-Nachricht eingeben kann.

Wenn -m <msg> oder -F <file> oder --trailer <token>[=<value>] angegeben wird und -a, -s und -u <key-id> fehlen, wird -a impliziert.

Andernfalls wird eine Tag-Referenz erstellt, die direkt auf das angegebene Objekt zeigt (d.h. ein Lightweight-Tag).

Ein kryptografisch signiertes Tag-Objekt wird erstellt, wenn -s oder -u <key-id> verwendet wird. Das Signierungsbackend (GPG, X.509, SSH usw.) wird durch die Konfigurationsvariable gpg.format gesteuert, die standardmäßig OpenPGP ist. Wenn -u <key-id> nicht verwendet wird, wird die Committer-Identität des aktuellen Benutzers verwendet, um den Schlüssel zum Signieren zu finden. Die Konfigurationsvariable gpg.program wird verwendet, um ein benutzerdefiniertes Signierungsbinary anzugeben.

Tag-Objekte (erstellt mit -a, -s oder -u) werden als "annotated" Tags bezeichnet; sie enthalten ein Erstellungsdatum, den Namen und die E-Mail-Adresse des Taggers, eine Tag-Nachricht und eine optionale kryptografische Signatur. Ein "lightweight" Tag ist dagegen einfach ein Name für ein Objekt (normalerweise ein Commit-Objekt).

Annotated-Tags sind für Releases gedacht, während Lightweight-Tags für private oder temporäre Objektbezeichnungen gedacht sind. Aus diesem Grund ignorieren einige Git-Befehle zum Benennen von Objekten (wie z.B. git describe) standardmäßig Lightweight-Tags.

OPTIONEN

-a
--annotate

Erstellt ein unsigniertes, annotiertes Tag-Objekt

-s
--sign

Erstellt ein kryptografisch signiertes Tag mit dem Standard-Signierschlüssel. Das verwendete Signierungsbackend hängt von der Konfigurationsvariable gpg.format ab. Der Standard-Schlüssel wird vom Backend bestimmt. Für GPG basiert er auf der E-Mail-Adresse des Committters, während er für SSH eine bestimmte Schlüsseldatei oder Agent-Identität sein kann. Siehe git-config[1].

--no-sign

Überschreibt die Konfigurationsvariable tag.gpgSign, die so eingestellt ist, dass jedes einzelne Tag signiert wird.

-u <key-id>
--local-user=<key-id>

Erstellt ein kryptografisch signiertes Tag mit dem angegebenen Schlüssel. Das Format des <key-id> und das verwendete Backend hängen von der Konfigurationsvariable gpg.format ab. Siehe git-config[1].

-f
--force

Ersetzt ein vorhandenes Tag mit dem angegebenen Namen (statt einen Fehler auszugeben)

-d
--delete

Löscht vorhandene Tags mit den angegebenen Namen.

-v
--verify

Überprüft die kryptografische Signatur der angegebenen Tags.

-n<num>

<num> gibt an, wie viele Zeilen aus der Annotation, falls vorhanden, beim Verwenden von -l gedruckt werden. Impliziert --list.

Standardmäßig werden keine Annotationszeilen gedruckt. Wenn keine Zahl an -n übergeben wird, wird nur die erste Zeile gedruckt. Wenn der Tag nicht annotiert ist, wird stattdessen die Commit-Nachricht angezeigt.

-l
--list

Listet Tags auf. Mit optionalem <pattern>..., z.B. git tag --list v-*', werden nur die Tags aufgelistet, die mit den Mustern übereinstimmen.

Wenn git tag ohne Argumente aufgerufen wird, werden ebenfalls alle Tags aufgelistet. Das Muster ist ein Shell-Wildcard (d.h. übereinstimmend mit fnmatch(3)). Mehrere Muster können angegeben werden; wenn eines davon übereinstimmt, wird der Tag angezeigt.

Diese Option wird implizit bereitgestellt, wenn eine andere Listen-ähnliche Option (wie --contains) angegeben wird. Details hierzu finden Sie in der Dokumentation für jede dieser Optionen.

--sort=<key>

Sortiert basierend auf dem angegebenen Schlüssel. Präfix -, um in absteigender Reihenfolge des Werts zu sortieren. Sie können die Option --sort=<key> mehrmals verwenden, wobei der letzte <key> zum Primärschlüssel wird. Unterstützt auch "version:refname" oder "v:refname" (Tag-Namen werden als Versionen behandelt). Die Sortierung "version:refname" kann auch durch die Konfigurationsvariable "versionsort.suffix" beeinflusst werden. Die unterstützten Schlüssel sind dieselben wie bei git for-each-ref. Die Sortierreihenfolge ist standardmäßig der Wert, der für die Variable tag.sort konfiguriert ist, falls vorhanden, andernfalls lexikografische Ordnung. Siehe git-config[1].

--color[=<when>]

Berücksichtigt alle Farben, die in der Option --format angegeben sind. Das Feld <when> muss entweder always, never oder auto sein (wenn <when> fehlt, wird es so behandelt, als wäre always angegeben).

-i
--ignore-case

Sortierung und Filterung von Tags sind case-insensitiv.

--omit-empty

Druckt keine neue Zeile nach formatierten Refs, bei denen das Format zu einer leeren Zeichenkette expandiert.

--column[=<options>]
--no-column

Zeigt die Tag-Liste in Spalten an. Siehe die Konfigurationsvariable column.tag für die Syntax der Optionen. --column und --no-column ohne Optionen sind äquivalent zu always bzw. never.

Diese Option ist nur anwendbar, wenn Tags ohne Annotationszeilen aufgelistet werden.

--contains [<commit>]

Listet nur Tags auf, die <commit> enthalten (standardmäßig HEAD). Impliziert --list.

--no-contains [<commit>]

Listet nur Tags auf, die <commit> nicht enthalten (standardmäßig HEAD). Impliziert --list.

--merged [<commit>]

Listet nur Tags auf, deren Commits von <commit> (standardmäßig HEAD) erreichbar sind.

--no-merged [<commit>]

Listet nur Tags auf, deren Commits nicht von <commit> (standardmäßig HEAD) erreichbar sind.

--points-at [<object>]

Listet nur Tags von <object> (standardmäßig HEAD) auf. Impliziert --list.

-m <msg>
--message=<msg>

Verwendet <msg> (statt zur Eingabe aufzufordern). Wenn mehrere -m-Optionen angegeben werden, werden ihre Werte als separate Absätze verkettet. Impliziert -a, wenn keine der Optionen -a, -s oder -u <key-id> angegeben wird.

-F <file>
--file=<file>

Nimmt die Tag-Nachricht aus <file>. Verwenden Sie -, um die Nachricht von der Standardeingabe zu lesen. Impliziert -a, wenn keine der Optionen -a, -s oder -u <key-id> angegeben wird.

--trailer <token>[(=|:)<value>]

Gibt ein (<token>, <value>)-Paar an, das als Trailer angewendet werden soll. (z.B. git tag --trailer "Custom-Key: value" fügt der Tag-Nachricht einen "Custom-Key"-Trailer hinzu.) Die Konfigurationsvariablen trailer.* (git-interpret-trailers[1]) können verwendet werden, um festzulegen, ob ein doppelter Trailer weggelassen wird, an welcher Stelle in der Liste der Trailer jeder Trailer erscheinen soll und weitere Details. Die Trailer können in git tag --list extrahiert werden, indem der Platzhalter --format="%(trailers)" verwendet wird.

-e
--edit

Ermöglicht die weitere Bearbeitung der Nachricht, die aus einer Datei mit -F und von der Kommandozeile mit -m übernommen wurde.

--cleanup=<mode>

Legt fest, wie die Tag-Nachricht bereinigt wird. Der <mode> kann einer der folgenden sein: verbatim, whitespace und strip. Der strip-Modus ist Standard. Der verbatim-Modus ändert die Nachricht überhaupt nicht, whitespace entfernt nur führende/nachfolgende Leerzeilen und strip entfernt sowohl Leerzeichen als auch Kommentare.

--create-reflog

Erstellt einen Reflog für das Tag. Um Reflogs für Tags global zu aktivieren, siehe core.logAllRefUpdates in git-config[1]. Die negierte Form --no-create-reflog überschreibt nur ein früheres --create-reflog, negiert aber derzeit nicht die Einstellung von core.logAllRefUpdates.

--format=<format>

Eine Zeichenkette, die %(fieldname) aus einem angezeigten Tag-Ref und dem Objekt, auf das es zeigt, interpoliert. Das Format ist dasselbe wie bei git-for-each-ref[1]. Wenn nicht angegeben, wird standardmäßig %(refname:strip=2) verwendet.

<tagname>

Der Name des zu erstellenden, zu löschenden oder zu beschreibenden Tags. Der neue Tag-Name muss alle von git-check-ref-format[1] definierten Prüfungen bestehen. Einige dieser Prüfungen können die Zeichen einschränken, die in einem Tag-Namen zulässig sind.

<commit>
<object>

Das Objekt, auf das der neue Tag zeigen wird, normalerweise ein Commit. Standardmäßig HEAD.

KONFIGURATION

Standardmäßig verwendet git tag im Signierungsmodus mit Standardwert (-s) Ihre Committer-Identität (im Format Your Name <your@email.address>), um einen Schlüssel zu finden. Wenn Sie einen anderen Standard-Schlüssel verwenden möchten, können Sie ihn in der Repository-Konfiguration wie folgt angeben:

[user]
    signingKey = <key-id>

Das Signierungsbackend kann über die Konfigurationsvariable gpg.format ausgewählt werden, die standardmäßig openpgp ist. Siehe git-config[1] für eine Liste anderer unterstützter Formate.

Der Pfad zum Programm, das für jedes Signierungsbackend verwendet wird, kann mit der Konfigurationsvariable gpg.<format>.program angegeben werden. Für das openpgp-Backend kann gpg.program als Synonym für gpg.openpgp.program verwendet werden. Siehe git-config[1] für Details.

pager.tag wird nur berücksichtigt, wenn Tags aufgelistet werden, d.h. wenn -l verwendet oder impliziert wird. Standardmäßig wird ein Pager verwendet.

Weitere Details und andere Konfigurationsvariablen finden Sie unter git-config[1].

DISKUSSION

Beim erneuten Taggen

Was tun Sie, wenn Sie einen falschen Commit getaggt haben und den Tag ändern möchten?

Wenn Sie noch nichts veröffentlicht haben, ändern Sie den Tag einfach. Verwenden Sie -f, um den alten zu ersetzen. Und Sie sind fertig.

Aber wenn Sie etwas veröffentlicht haben (oder andere Ihr Repository direkt lesen können), dann haben andere den alten Tag bereits gesehen. In diesem Fall können Sie eines von zwei Dingen tun:

  1. Die vernünftige Sache. Geben Sie einfach zu, dass Sie einen Fehler gemacht haben, und verwenden Sie einen anderen Namen. Andere haben bereits einen Tag-Namen gesehen, und wenn Sie denselben Namen beibehalten, könnten Sie in der Situation sein, dass zwei Personen "Version X" haben, aber tatsächlich *unterschiedliche* "X"s haben. Nennen Sie es also einfach "X.1" und fertig.

  2. Die unsinnige Sache. Sie möchten die neue Version wirklich auch "X" nennen, *obwohl* andere sie bereits gesehen haben. Verwenden Sie also einfach erneut git tag -f, als hätten Sie den alten noch nicht veröffentlicht.

Git ändert jedoch Tags nicht (und sollte dies auch nicht) hinter dem Rücken der Benutzer. Wenn also jemand den alten Tag erhalten hat, sollte ein git pull von Ihrem Baum nicht einfach dazu führen, dass dieser den alten überschreibt.

Wenn jemand einen Release-Tag von Ihnen erhalten hat, können Sie den Tag nicht einfach für ihn ändern, indem Sie Ihren eigenen aktualisieren. Dies ist ein großes Sicherheitsproblem, da Personen sich auf ihre Tag-Namen verlassen können müssen. Wenn Sie die unsinnige Sache wirklich tun wollen, müssen Sie es einfach zugeben und den Leuten sagen, dass Sie sich geirrt haben. Sie können dies tun, indem Sie eine sehr öffentliche Ankündigung machen, die besagt:

Ok, I messed up, and I pushed out an earlier version tagged as X. I
then fixed something, and retagged the *fixed* tree as X again.

If you got the wrong tag, and want the new one, please delete
the old one and fetch the new one by doing:

	git tag -d X
	git fetch origin tag X

to get my updated tag.

You can test which tag you have by doing

	git rev-parse X

which should return 0123456789abcdef.. if you have the new version.

Sorry for the inconvenience.

Scheint das etwas kompliziert? Das sollte es auch sein. Es gibt keine Möglichkeit, dies automatisch zu "korrigieren". Die Leute müssen wissen, dass ihre Tags möglicherweise geändert wurden.

Zur automatischen Verfolgung

Wenn Sie den Baum eines anderen verfolgen, verwenden Sie höchstwahrscheinlich Remote-Tracking-Branches (z.B. refs/remotes/origin/master). Sie möchten normalerweise die Tags vom anderen Ende haben.

Andererseits, wenn Sie Fetchen, weil Sie eine einmalige Zusammenführung von jemand anderem wünschen, möchten Sie in der Regel keine Tags von dort erhalten. Dies geschieht häufiger bei Personen am oberen Ende, aber nicht nur bei ihnen. Normale Benutzer, die voneinander ziehen, möchten nicht unbedingt automatisch private Ankerpunkt-Tags vom anderen erhalten.

Oft geben "please pull"-Nachrichten in Mailinglisten nur zwei Informationen: eine Repo-URL und einen Branch-Namen. Dies ist so konzipiert, dass es leicht in eine git fetch-Befehlszeile kopiert und eingefügt werden kann.

Linus, please pull from

	git://git..../proj.git master

to get the following updates...

wird zu

$ git pull git://git..../proj.git master

In einem solchen Fall möchten Sie die Tags des anderen nicht automatisch verfolgen.

Ein wichtiger Aspekt von Git ist seine verteilte Natur, was weitgehend bedeutet, dass es im System kein inhärentes "Upstream" oder "Downstream" gibt. Oberflächlich betrachtet könnte das obige Beispiel darauf hindeuten, dass der Tag-Namespace von der obersten Schicht der Leute besessen ist und dass Tags nur nach unten fließen, aber das ist nicht der Fall. Es zeigt nur, dass das Nutzungsmuster bestimmt, wer an wessen Tags interessiert ist.

Ein einmaliger Pull ist ein Zeichen dafür, dass eine Commit-Historie jetzt die Grenze zwischen einem Kreis von Leuten (z.B. "Leute, die sich hauptsächlich für den Netzwerkteil des Kernels interessieren") mit ihren eigenen Tags (z.B. "Dies ist der dritte Release Candidate der Netzwerkgruppe, der für den allgemeinen Gebrauch mit der Veröffentlichung 2.6.21 vorgeschlagen wird") zu einem anderen Kreis von Leuten (z.B. "Leute, die verschiedene Subsystem-Verbesserungen integrieren") überquert. Letztere sind normalerweise nicht an den detaillierten Tags interessiert, die intern in der ersteren Gruppe verwendet werden (das bedeutet "intern"). Deshalb ist es wünschenswert, Tags in diesem Fall nicht automatisch zu verfolgen.

Es mag sein, dass Netzwerk-Leute untereinander interne Tags austauschen wollen, aber in diesem Workflow verfolgen sie höchstwahrscheinlich die Fortschritte voneinander, indem sie Remote-Tracking-Branches haben. Auch hier ist die Heuristik, solche Tags automatisch zu verfolgen, eine gute Sache.

Zur Rückdatierung von Tags

Wenn Sie Änderungen aus einem anderen VCS importiert haben und Tags für wichtige Releases Ihrer Arbeit hinzufügen möchten, ist es nützlich, das Datum angeben zu können, das in das Tag-Objekt eingebettet werden soll; solche Daten im Tag-Objekt beeinflussen beispielsweise die Reihenfolge der Tags in der Gitweb-Oberfläche.

Um das Datum für zukünftige Tag-Objekte festzulegen, setzen Sie die Umgebungsvariable GIT_COMMITTER_DATE (siehe die spätere Diskussion möglicher Werte; die gängigste Form ist "JJJJ-MM-TT HH:MM").

Zum Beispiel

$ GIT_COMMITTER_DATE="2006-10-02 10:31" git tag -s v1.0.1

DATUMSFORMATE

Die Umgebungsvariablen GIT_AUTHOR_DATE und GIT_COMMITTER_DATE unterstützen die folgenden Datumsformate:

Git internes Format

Es ist <unix-timestamp> <time-zone-offset>, wobei <unix-timestamp> die Anzahl der Sekunden seit der UNIX-Epoche ist. <time-zone-offset> ist ein positiver oder negativer Offset von UTC. Zum Beispiel ist CET (das 1 Stunde vor UTC liegt) +0100.

RFC 2822

Das Standard-Datumsformat wie in RFC 2822 beschrieben, zum Beispiel Thu, 07 Apr 2005 22:13:13 +0200.

ISO 8601

Zeit und Datum gemäß dem ISO 8601-Standard, zum Beispiel 2005-04-07T22:13:13. Der Parser akzeptiert auch ein Leerzeichen anstelle des T-Zeichens. Bruchteile von Sekunden werden ignoriert, zum Beispiel wird 2005-04-07T22:13:13.019 als 2005-04-07T22:13:13 behandelt.

Hinweis
 Zusätzlich werden Datumsangaben in den folgenden Formaten akzeptiert: JJJJ.MM.TT, MM/TT/JJJJ und TT.MM.JJJJ.

DATEIEN

$GIT_DIR/TAG_EDITMSG

Diese Datei enthält die Nachricht eines im Gange befindlichen annotierten Tags. Wenn git tag aufgrund eines Fehlers beendet wird, bevor ein annotiertes Tag erstellt wird, ist die vom Benutzer in einer Editorsitzung bereitgestellte Tag-Nachricht in dieser Datei verfügbar, kann aber bei der nächsten Ausführung von git tag überschrieben werden.

KONFIGURATION

Alles unterhalb dieser Zeile in diesem Abschnitt wird selektiv aus der git-config[1]-Dokumentation übernommen. Der Inhalt ist derselbe wie dort zu finden.

tag.forceSignAnnotated

Ein boolescher Wert, der angibt, ob erstellte annotierte Tags GPG-signiert werden sollen. Wenn --annotate auf der Kommandozeile angegeben wird, hat dies Vorrang vor dieser Option.

tag.sort

Diese Variable steuert die Sortierreihenfolge von Tags, wenn sie von git-tag angezeigt werden. Ohne die Option --sort=<value> wird der Wert dieser Variable als Standard verwendet.

tag.gpgSign

Ein boolescher Wert, der angibt, ob alle Tags GPG-signiert werden sollen. Die Verwendung dieser Option in einem automatisierten Skript kann dazu führen, dass eine große Anzahl von Tags signiert wird. Es ist daher praktisch, einen Agenten zu verwenden, um zu vermeiden, dass Ihre GPG-Passphrase mehrmals eingegeben werden muss. Beachten Sie, dass diese Option das Tag-Signierungsverhalten, das durch die Optionen -u <keyid> oder --local-user=<keyid> aktiviert wird, nicht beeinflusst.

ANMERKUNGEN

Bei der Kombination mehrerer --contains- und --no-contains-Filter werden nur Referenzen angezeigt, die mindestens einen der --contains-Commits enthalten und keinen der --no-contains-Commits enthalten.

Bei der Kombination mehrerer --merged- und --no-merged-Filter werden nur Referenzen angezeigt, die von mindestens einem der --merged-Commits erreichbar sind und von keinem der --no-merged-Commits.

SIEHE AUCH

git-check-ref-format[1]. git-config[1].

GIT

Teil der git[1] Suite