English ▾ Themen ▾ Neueste Version ▾ git-interpret-trailers zuletzt aktualisiert in 2.51.1

NAME

git-interpret-trailers - Strukturierte Informationen in Commit-Nachrichten hinzufügen oder parsen

SYNOPSIS

git interpret-trailers [--in-place] [--trim-empty]
			[(--trailer (<key>|<key-alias>)[(=|:)<value>])…​]
			[--parse] [<file>…​]

BESCHREIBUNG

Fügt am Ende des ansonsten frei formatierten Teils einer Commit-Nachricht "Trailer"-Zeilen hinzu oder parst diese, die RFC 822 E-Mail-Headern ähneln. Zum Beispiel in der folgenden Commit-Nachricht

subject

Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Signed-off-by: Alice <alice@example.com>
Signed-off-by: Bob <bob@example.com>

sind die letzten beiden Zeilen, die mit "Signed-off-by" beginnen, Trailer.

Dieser Befehl liest Commit-Nachrichten entweder aus den <Datei>-Argumenten oder vom Standardeingang, wenn keine <Datei> angegeben ist. Wenn --parse angegeben ist, besteht die Ausgabe aus den geparsten Trailern aus der Eingabe, ohne diese durch Kommandozeilenoptionen oder Konfigurationsvariablen zu beeinflussen.

Andernfalls wendet dieser Befehl die Konfigurationsvariablen trailer.* (die potenziell neue Trailer hinzufügen sowie deren Position ändern können), sowie alle Kommandozeilenargumente, die Konfigurationsvariablen überschreiben können (wie z.B. --trailer=..., das ebenfalls neue Trailer hinzufügen kann), auf jede Eingabedatei an. Das Ergebnis wird auf der Standardausgabe ausgegeben.

Dieser Befehl kann auch auf die Ausgabe von git-format-patch[1] angewendet werden, welche ausgefeilter ist als eine einfache Commit-Nachricht. Insbesondere enthält eine solche Ausgabe eine Commit-Nachricht (wie oben), eine "---" Trennlinie und einen Patch-Teil. Für diese Eingaben werden die Trennlinie und die Patch-Teile von diesem Befehl nicht modifiziert und wie sie sind auf die Ausgabe ausgegeben, es sei denn, --no-divider ist angegeben.

Einige Konfigurationsvariablen steuern, wie die --trailer-Argumente auf jede Eingabe angewendet werden und wie vorhandene Trailer in der Eingabe geändert werden. Sie ermöglichen es auch, automatisch einige Trailer hinzuzufügen.

Standardmäßig wird ein mit --trailer übergebenes Argument vom Typ <Schlüssel>=<Wert> oder <Schlüssel>:<Wert> nur dann nach den vorhandenen Trailern angehängt, wenn der letzte Trailer ein anderes (<Schlüssel>, <Wert>)-Paar hat (oder wenn kein vorhandener Trailer existiert). Die <Schlüssel>- und <Wert>-Teile werden gekürzt, um führende und nachgestellte Leerzeichen zu entfernen, und der resultierende gekürzte <Schlüssel> und <Wert> erscheinen in der Ausgabe wie folgt

key: value

Dies bedeutet, dass der gekürzte <Schlüssel> und <Wert> durch : (ein Doppelpunkt gefolgt von einem Leerzeichen) getrennt werden.

Zur Vereinfachung kann ein <Schlüssel-Alias> konfiguriert werden, um die Verwendung von --trailer auf der Kommandozeile kürzer zu gestalten. Dies kann über die Konfigurationsvariable trailer.<Schlüssel-Alias>.key konfiguriert werden. Der <Schlüssel-Alias> muss ein Präfix des vollständigen <Schlüssel>-Strings sein, wobei die Groß-/Kleinschreibung nicht beachtet wird. Wenn Sie zum Beispiel

trailer.sign.key "Signed-off-by: "

in Ihrer Konfiguration haben, müssen Sie auf der Kommandozeile nur --trailer="sign: foo" anstelle von --trailer="Signed-off-by: foo" angeben.

Standardmäßig erscheint der neue Trailer am Ende aller vorhandenen Trailer. Wenn kein vorhandener Trailer existiert, erscheint der neue Trailer am Ende der Eingabe. Vor dem neuen Trailer wird eine Leerzeile hinzugefügt, falls noch keine vorhanden ist.

Vorhandene Trailer werden aus der Eingabe extrahiert, indem nach einer Gruppe von einer oder mehreren Zeilen gesucht wird, die (i) ausschließlich Trailer sind, oder (ii) mindestens einen von Git generierten oder benutzerkonfigurierten Trailer enthalten und zu mindestens 25 % aus Trailern bestehen. Die Gruppe muss von einer oder mehreren leeren (oder nur Leerzeichen enthaltenden) Zeilen vorangestellt sein. Die Gruppe muss entweder am Ende der Eingabe stehen oder die letzten nicht-leeren Zeilen vor einer Zeile sein, die mit --- beginnt (gefolgt von einem Leerzeichen oder dem Zeilenende).

Beim Lesen von Trailern dürfen keine Leerzeichen vor oder innerhalb des <Schlüssel> stehen, aber zwischen dem <Schlüssel> und dem Trennzeichen sind beliebig viele normale Leerzeichen und Tabulatoren erlaubt. Vor, innerhalb oder nach dem <Wert> dürfen Leerzeichen stehen. Der <Wert> kann über mehrere Zeilen verteilt sein, wobei jede nachfolgende Zeile mit mindestens einem Leerzeichen beginnt, ähnlich dem "Falten" in RFC 822. Beispiel

key: This is a very long value, with spaces and
  newlines in it.

Beachten Sie, dass Trailer nicht (und nicht beabsichtigt sind) viele der Regeln für RFC 822-Header befolgen. Zum Beispiel folgen sie nicht der Kodierungsregel.

OPTIONEN

--in-place

Bearbeitet die Dateien direkt.

--trim-empty

Wenn der <Wert>-Teil eines Trailers nur Leerzeichen enthält, wird der gesamte Trailer aus der Ausgabe entfernt. Dies gilt sowohl für vorhandene Trailer als auch für neue Trailer.

--trailer <Schlüssel>[(=|:)<Wert>]

Gibt ein (<Schlüssel>, <Wert>)-Paar an, das als Trailer auf die Eingaben angewendet werden soll. Siehe die Beschreibung dieses Befehls.

--where <Platzierung>
--no-where

Gibt an, wo alle neuen Trailer hinzugefügt werden. Eine mit --where angegebene Einstellung überschreibt die trailer.where und alle anwendbaren trailer.<Schlüssel-Alias>.where Konfigurationsvariablen und gilt für alle --trailer-Optionen bis zur nächsten Nennung von --where oder --no-where. Beim Erreichen von --no-where wird die Auswirkung einer früheren Verwendung von --where aufgehoben, so dass die relevanten Konfigurationsvariablen nicht mehr überschrieben werden. Mögliche Platzierungen sind after, before, end oder start.

--if-exists <Aktion>
--no-if-exists

Gibt an, welche Aktion ausgeführt wird, wenn bereits mindestens ein Trailer mit demselben <Schlüssel> in der Eingabe vorhanden ist. Eine mit --if-exists angegebene Einstellung überschreibt die trailer.ifExists und alle anwendbaren trailer.<Schlüssel-Alias>.ifExists Konfigurationsvariablen und gilt für alle --trailer-Optionen bis zur nächsten Nennung von --if-exists oder --no-if-exists. Beim Erreichen von --no-if-exists wird die Auswirkung einer früheren Verwendung von --if-exists aufgehoben, so dass die relevanten Konfigurationsvariablen nicht mehr überschrieben werden. Mögliche Aktionen sind addIfDifferent, addIfDifferentNeighbor, add, replace und doNothing.

--if-missing <Aktion>
--no-if-missing

Gibt an, welche Aktion ausgeführt wird, wenn noch kein Trailer mit demselben <Schlüssel> in der Eingabe vorhanden ist. Eine mit --if-missing angegebene Einstellung überschreibt die trailer.ifMissing und alle anwendbaren trailer.<Schlüssel-Alias>.ifMissing Konfigurationsvariablen und gilt für alle --trailer-Optionen bis zur nächsten Nennung von --if-missing oder --no-if-missing. Beim Erreichen von --no-if-missing wird die Auswirkung einer früheren Verwendung von --if-missing aufgehoben, so dass die relevanten Konfigurationsvariablen nicht mehr überschrieben werden. Mögliche Aktionen sind doNothing oder add.

--only-trailers

Gibt nur die Trailer aus, nicht alle anderen Teile der Eingabe.

--only-input

Gibt nur Trailer aus, die in der Eingabe vorhanden sind; fügt keine von der Kommandozeile oder durch Anwendung von trailer.* Konfigurationsvariablen hinzu.

--unfold

Wenn ein Trailer einen Wert hat, der sich über mehrere Zeilen erstreckt (auch "gefaltet" genannt), formatiert er den Wert in eine einzige Zeile.

--parse

Ein praktisches Alias für --only-trailers --only-input --unfold. Dies erleichtert das Anzeigen nur der Trailer aus der Eingabe, ohne sie durch Kommandozeilenoptionen oder Konfigurationsvariablen zu beeinflussen, und macht die Ausgabe mit --unfold maschinenfreundlich.

--no-divider

Behandelt --- nicht als Ende der Commit-Nachricht. Verwenden Sie dies, wenn Sie wissen, dass Ihre Eingabe nur die Commit-Nachricht selbst enthält (und nicht eine E-Mail oder die Ausgabe von git format-patch).

KONFIGURATION VARIABLEN

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

trailer.separators

Diese Option gibt an, welche Zeichen als Trennzeichen für Trailer erkannt werden. Standardmäßig wird nur : als Trennzeichen für Trailer erkannt, mit der Ausnahme, dass = aus Kompatibilitätsgründen mit anderen Git-Befehlen immer auf der Kommandozeile akzeptiert wird.

Das erste durch diese Option angegebene Zeichen ist das Standardzeichen, das verwendet wird, wenn in der Konfiguration kein anderes Trennzeichen für diesen Trailer angegeben ist.

Wenn zum Beispiel der Wert für diese Option "%=$" ist, dann werden nur Zeilen im Format <Schlüssel><Trenner><Wert> mit <Trenner>, der %, = oder $ und dann Leerzeichen enthält, als Trailer betrachtet. Und % ist der Standardtrenner, so dass Trailer standardmäßig wie folgt aussehen: <Schlüssel>% <Wert> (ein Prozentzeichen und ein Leerzeichen erscheinen zwischen Schlüssel und Wert).

trailer.where

Diese Option gibt an, wo ein neuer Trailer hinzugefügt wird.

Dies kann end sein, was der Standard ist, start, after oder before.

Wenn es end ist, erscheint jeder neue Trailer am Ende der vorhandenen Trailer.

Wenn es start ist, erscheint jeder neue Trailer stattdessen am Anfang der vorhandenen Trailer.

Wenn es after ist, erscheint jeder neue Trailer direkt nach dem letzten Trailer mit demselben <Schlüssel>.

Wenn es before ist, erscheint jeder neue Trailer direkt vor dem ersten Trailer mit demselben <Schlüssel>.

trailer.ifexists

Diese Option ermöglicht die Wahl, welche Aktion ausgeführt wird, wenn bereits mindestens ein Trailer mit demselben <Schlüssel> in der Eingabe vorhanden ist.

Die gültigen Werte für diese Option sind: addIfDifferentNeighbor (dies ist der Standard), addIfDifferent, add, replace oder doNothing.

Mit addIfDifferentNeighbor wird ein neuer Trailer nur hinzugefügt, wenn kein Trailer mit demselben (<Schlüssel>, <Wert>)-Paar über oder unter der Zeile liegt, in die der neue Trailer eingefügt wird.

Mit addIfDifferent wird ein neuer Trailer nur hinzugefügt, wenn kein Trailer mit demselben (<Schlüssel>, <Wert>)-Paar bereits in der Eingabe vorhanden ist.

Mit add wird ein neuer Trailer hinzugefügt, auch wenn bereits einige Trailer mit demselben (<Schlüssel>, <Wert>)-Paar in der Eingabe vorhanden sind.

Mit replace wird ein vorhandener Trailer mit demselben <Schlüssel> gelöscht und der neue Trailer hinzugefügt. Der gelöschte Trailer ist derjenige, der dem Ort, an dem der neue hinzugefügt wird, am nächsten liegt (mit demselben <Schlüssel>).

Mit doNothing wird nichts unternommen; das heißt, es wird kein neuer Trailer hinzugefügt, wenn bereits einer mit demselben <Schlüssel> in der Eingabe vorhanden ist.

trailer.ifmissing

Diese Option ermöglicht die Wahl, welche Aktion ausgeführt wird, wenn noch kein Trailer mit demselben <Schlüssel> in der Eingabe vorhanden ist.

Die gültigen Werte für diese Option sind: add (dies ist der Standard) und doNothing.

Mit add wird ein neuer Trailer hinzugefügt.

Mit doNothing wird nichts unternommen.

trailer.<Schlüssel-Alias>.key

Definiert einen <Schlüssel-Alias> für den <Schlüssel>. Der <Schlüssel-Alias> muss ein Präfix (Groß-/Kleinschreibung wird nicht beachtet) des <Schlüssel> sein. Wenn Sie zum Beispiel in git config trailer.ack.key "Acked-by" "Acked-by" den <Schlüssel> und "ack" den <Schlüssel-Alias> bezeichnet, erlaubt diese Konfiguration die kürzere Eingabeaufforderung --trailer "ack:..." auf der Kommandozeile anstelle der längeren Eingabeaufforderung --trailer "Acked-by:...".

Am Ende des <Schlüssel> kann ein Trennzeichen und dann einige Leerzeichen erscheinen. Standardmäßig ist das einzige gültige Trennzeichen :, dies kann jedoch mit der Konfigurationsvariable trailer.separators geändert werden.

Wenn ein Trennzeichen im Schlüssel vorhanden ist, überschreibt es das Standardtrennzeichen beim Hinzufügen des Trailers.

trailer.<Schlüssel-Alias>.where

Diese Option nimmt dieselben Werte an wie die Konfigurationsvariable trailer.where und überschreibt das, was von dieser Option für Trailer mit dem angegebenen <Schlüssel-Alias> spezifiziert wird.

trailer.<Schlüssel-Alias>.ifexists

Diese Option nimmt dieselben Werte an wie die Konfigurationsvariable trailer.ifexists und überschreibt das, was von dieser Option für Trailer mit dem angegebenen <Schlüssel-Alias> spezifiziert wird.

trailer.<Schlüssel-Alias>.ifmissing

Diese Option nimmt dieselben Werte an wie die Konfigurationsvariable trailer.ifmissing und überschreibt das, was von dieser Option für Trailer mit dem angegebenen <Schlüssel-Alias> spezifiziert wird.

trailer.<Schlüssel-Alias>.command

Veraltet zugunsten von trailer.<Schlüssel-Alias>.cmd. Diese Option verhält sich genauso wie trailer.<Schlüssel-Alias>.cmd, außer dass sie nichts als Argument an den angegebenen Befehl übergibt. Stattdessen wird die erste Vorkommens des Teilstrings $ARG durch den <Wert> ersetzt, der als Argument übergeben würde.

Beachten Sie, dass $ARG im Befehl des Benutzers nur einmal ersetzt wird und dass die ursprüngliche Methode des Ersetzens von $ARG nicht sicher ist.

Wenn sowohl trailer.<Schlüssel-Alias>.cmd als auch trailer.<Schlüssel-Alias>.command für denselben <Schlüssel-Alias> angegeben werden, wird trailer.<Schlüssel-Alias>.cmd verwendet und trailer.<Schlüssel-Alias>.command wird ignoriert.

trailer.<Schlüssel-Alias>.cmd

Diese Option kann verwendet werden, um einen Shell-Befehl anzugeben, der einmal aufgerufen wird, um automatisch einen Trailer mit dem angegebenen <Schlüssel-Alias> hinzuzufügen, und der dann jedes Mal aufgerufen wird, wenn ein Argument --trailer <Schlüssel-Alias>=<Wert> angegeben wird, um den <Wert> des Trailers zu ändern, den diese Option erzeugen würde.

Wenn der angegebene Befehl zum ersten Mal aufgerufen wird, um einen Trailer mit dem angegebenen <Schlüssel-Alias> hinzuzufügen, verhält es sich so, als wäre ein spezielles Argument --trailer <Schlüssel-Alias>=<Wert> am Anfang des Befehls "git interpret-trailers" hinzugefügt worden, wobei der <Wert> die Standardausgabe des Befehls ist, wobei führende und nachgestellte Leerzeichen abgeschnitten werden.

Wenn auch einige --trailer <Schlüssel-Alias>=<Wert>-Argumente auf der Kommandozeile übergeben werden, wird der Befehl einmal für jedes dieser Argumente mit demselben <Schlüssel-Alias> erneut aufgerufen. Und der <Wert>-Teil dieser Argumente, falls vorhanden, wird dem Befehl als erstes Argument übergeben. Auf diese Weise kann der Befehl einen <Wert> erzeugen, der aus dem <Wert> berechnet wird, der im --trailer <Schlüssel-Alias>=<Wert>-Argument übergeben wird.

BEISPIELE

  • Konfigurieren Sie einen sign-Trailer mit dem Schlüssel Signed-off-by und fügen Sie dann zwei dieser Trailer einer Commit-Nachrichtendatei hinzu

    $ git config trailer.sign.key "Signed-off-by"
$ cat msg.txt
subject

body text
$ git interpret-trailers --trailer 'sign: Alice <alice@example.com>' --trailer 'sign: Bob <bob@example.com>' <msg.txt
subject

body text

Signed-off-by: Alice <alice@example.com>
Signed-off-by: Bob <bob@example.com>

  • Verwenden Sie die Option --in-place, um eine Commit-Nachrichtendatei direkt zu bearbeiten

    $ cat msg.txt
subject

body text

Signed-off-by: Bob <bob@example.com>
$ git interpret-trailers --trailer 'Acked-by: Alice <alice@example.com>' --in-place msg.txt
$ cat msg.txt
subject

body text

Signed-off-by: Bob <bob@example.com>
Acked-by: Alice <alice@example.com>

  • Extrahieren Sie den letzten Commit als Patch und fügen Sie ihm einen Cc- und einen Reviewed-by-Trailer hinzu

    $ git format-patch -1
0001-foo.patch
$ git interpret-trailers --trailer 'Cc: Alice <alice@example.com>' --trailer 'Reviewed-by: Bob <bob@example.com>' 0001-foo.patch >0001-bar.patch

  • Konfigurieren Sie einen sign-Trailer mit einem Befehl, um automatisch ein 'Signed-off-by: ' mit nur den Autoreninformationen hinzuzufügen, falls noch kein 'Signed-off-by: ' vorhanden ist, und zeigen Sie, wie er funktioniert

    $ cat msg1.txt
subject

body text
$ git config trailer.sign.key "Signed-off-by: "
$ git config trailer.sign.ifmissing add
$ git config trailer.sign.ifexists doNothing
$ git config trailer.sign.cmd 'echo "$(git config user.name) <$(git config user.email)>"'
$ git interpret-trailers --trailer sign <msg1.txt
subject

body text

Signed-off-by: Bob <bob@example.com>
$ cat msg2.txt
subject

body text

Signed-off-by: Alice <alice@example.com>
$ git interpret-trailers --trailer sign <msg2.txt
subject

body text

Signed-off-by: Alice <alice@example.com>

  • Konfigurieren Sie einen fix-Trailer mit einem Schlüssel, der ein # enthält und kein Leerzeichen nach diesem Zeichen, und zeigen Sie, wie er funktioniert

    $ git config trailer.separators ":#"
$ git config trailer.fix.key "Fix #"
$ echo "subject" | git interpret-trailers --trailer fix=42
subject

Fix #42

  • Konfigurieren Sie einen help-Trailer mit einem Befehl, der ein Skript glog-find-author verwendet, das eine angegebene Autorenidentität aus dem Git-Log in einem Git-Repository sucht, und zeigen Sie, wie er funktioniert

    $ cat ~/bin/glog-find-author
#!/bin/sh
test -n "$1" && git log --author="$1" --pretty="%an <%ae>" -1 || true
$ cat msg.txt
subject

body text
$ git config trailer.help.key "Helped-by: "
$ git config trailer.help.ifExists "addIfDifferentNeighbor"
$ git config trailer.help.cmd "~/bin/glog-find-author"
$ git interpret-trailers --trailer="help:Junio" --trailer="help:Couder" <msg.txt
subject

body text

Helped-by: Junio C Hamano <gitster@pobox.com>
Helped-by: Christian Couder <christian.couder@gmail.com>

  • Konfigurieren Sie einen ref-Trailer mit einem Befehl, der ein Skript glog-grep verwendet, um den letzten relevanten Commit aus dem Git-Log im Git-Repository zu durchsuchen, und zeigen Sie, wie er funktioniert

    $ cat ~/bin/glog-grep
#!/bin/sh
test -n "$1" && git log --grep "$1" --pretty=reference -1 || true
$ cat msg.txt
subject

body text
$ git config trailer.ref.key "Reference-to: "
$ git config trailer.ref.ifExists "replace"
$ git config trailer.ref.cmd "~/bin/glog-grep"
$ git interpret-trailers --trailer="ref:Add copyright notices." <msg.txt
subject

body text

Reference-to: 8bc9a0c769 (Add copyright notices., 2005-04-07)

  • Konfigurieren Sie einen see-Trailer mit einem Befehl, um den Betreff eines zugehörigen Commits anzuzeigen, und zeigen Sie, wie er funktioniert

    $ cat msg.txt
subject

body text

see: HEAD~2
$ cat ~/bin/glog-ref
#!/bin/sh
git log -1 --oneline --format="%h (%s)" --abbrev-commit --abbrev=14
$ git config trailer.see.key "See-also: "
$ git config trailer.see.ifExists "replace"
$ git config trailer.see.ifMissing "doNothing"
$ git config trailer.see.cmd "glog-ref"
$ git interpret-trailers --trailer=see <msg.txt
subject

body text

See-also: fe3187489d69c4 (subject of related commit)

  • Konfigurieren Sie eine Commit-Vorlage mit einigen Trailern mit leeren Werten (mit sed, um die nachgestellten Leerzeichen am Ende der Trailer anzuzeigen und zu erhalten) und konfigurieren Sie dann einen Commit-Nachrichten-Hook, der git interpret-trailers verwendet, um Trailer mit leeren Werten zu entfernen und einen git-version-Trailer hinzuzufügen

    $ cat temp.txt
***subject***

***message***

Fixes: Z
Cc: Z
Reviewed-by: Z
Signed-off-by: Z
$ sed -e 's/ Z$/ /' temp.txt > commit_template.txt
$ git config commit.template commit_template.txt
$ cat .git/hooks/commit-msg
#!/bin/sh
git interpret-trailers --trim-empty --trailer "git-version: \$(git describe)" "\$1" > "\$1.new"
mv "\$1.new" "\$1"
$ chmod +x .git/hooks/commit-msg

SIEHE AUCH

git-commit[1], git-format-patch[1], git-config[1]

GIT

Teil der git[1] Suite