git-interpret-trailers

Имя

git-interpret-trailers — добавление или разбор структурированной информации в сообщениях коммитов

Краткое описание

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

Описание

Добавляет или разбирает строки trailer, похожие на заголовки электронных писем RFC 822, в конце части сообщения коммита, которая в остальном имеет свободный формат. Например, в следующем сообщении коммита

subject

Lorem ipsum dolor sit amet, consectetur adipiscing elit.

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

последние две строки, начинающиеся с Signed-off-by, являются строками-трейлерами.

Эта команда считывает сообщения коммитов из аргументов <file> или из стандартного ввода, если <file> не указано. Если указано --parse, вывод содержит разобранные строки-трейлеры из входных данных без изменения под влиянием параметров командной строки или переменных конфигурации.

В противном случае команда применяет переменные конфигурации trailer.<key-alias> (которые могут добавлять новые строки-трейлеры и менять их расположение), а также любые аргументы командной строки, способные переопределять переменные конфигурации (например, --trailer=..., который также может добавлять новые строки-трейлеры), к каждому входному файлу. Результат выводится в стандартный поток вывода.

Эта команда также может обрабатывать вывод git-format-patch[1], который сложнее обычного сообщения коммита. Такой вывод содержит сообщение коммита (как описано выше), строку-разделитель --- и часть с патчем. Для таких входных данных разделитель и части с патчем не изменяются этой командой и выводятся без изменений, если не указан параметр --no-divider.

Некоторые переменные конфигурации управляют тем, как аргументы --trailer применяются к каждому входному файлу и как изменяются уже имеющиеся во входных данных строки-трейлеры. Они также позволяют автоматически добавлять некоторые строки-трейлеры.

По умолчанию аргумент <key>=<value> или <key>:<value>, заданный с помощью --trailer, добавляется после имеющихся строк-трейлеров, только если последняя строка-трейлер имеет другую пару (<key>, <value>) (или если строк-трейлеров нет). Части <key> и <value> обрезаются для удаления начальных и конечных пробелов, а полученные после обрезки <key> и <value> отображаются в выводе следующим образом:

key: value

Это означает, что обрезанные <key> и <value> разделяются строкой «: » (двоеточие, за которым следует пробел).

Для удобства можно настроить <key-alias>, чтобы сократить запись --trailer в командной строке. Для этого используется переменная конфигурации trailer.<key-alias>.key. <key-alias> должен быть префиксом полной строки <key>, регистр символов при этом не имеет значения. Например, если в конфигурации задано

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

в командной строке достаточно указать --trailer="sign: foo" вместо --trailer="Signed-off-by: foo".

По умолчанию новая строка-трейлер помещается в конец всех имеющихся строк-трейлеров. Если строк-трейлеров нет, новая строка-трейлер помещается в конец входных данных. Перед новой строкой-трейлером добавляется пустая строка, если ее там еще нет.

Имеющиеся строки-трейлеры извлекаются из входных данных путем поиска группы из одной или нескольких строк, которая (i) целиком состоит из строк-трейлеров или (ii) содержит хотя бы одну строку-трейлер, созданную Git или настроенную пользователем, и как минимум на 25% состоит из строк-трейлеров. Перед группой должна находиться одна или несколько пустых строк (или строк, содержащих только пробельные символы). Группа должна находиться либо в конце входных данных, либо быть последними строками, не содержащими пробельных символов, перед строкой, начинающейся с --- (за которым следует пробел или конец строки).

При чтении строк-трейлеров перед <key> или внутри него не допускаются пробельные символы, однако между <key> и разделителем допускается любое количество обычных пробелов и символов табуляции. Перед <value>, внутри или после него могут находиться пробельные символы. <value> может быть разбит на несколько строк, каждая из которых начинается как минимум с одного пробельного символа, как при «свертывании» строк в RFC 822. Пример:

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

Обратите внимание, что строки-трейлеры не следуют многим правилам для заголовков RFC 822 и не предназначены для этого. Например, они не следуют правилам кодирования.

Параметры

--in-place

--no-in-place

Редактировать файлы на месте. По умолчанию используется --no-in-place.

--trim-empty

--no-trim-empty

Если часть <value> какой-либо строки-трейлера содержит только пробельные символы, вся строка-трейлер удаляется из вывода. Это относится как к уже имеющимся строкам-трейлерам, так и к новым.

По умолчанию используется --no-trim-empty.

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

--no-trailer

Задать пару (<key>, <value>), которую следует применить к входным данным в качестве строки-трейлера. См. описание этой команды. Параметр можно указать несколько раз.

Используйте --no-trailer, чтобы сбросить список.

--where=<placement>

--no-where

Указать, куда добавлять все новые строки-трейлеры. Значение, заданное с помощью --where, переопределяет trailer.where и все применимые переменные конфигурации trailer.<key-alias>.where и применяется ко всем параметрам --trailer до следующего вхождения --where или --no-where. Возможные места размещения: after, before, end или start.

Используйте --no-where, чтобы отменить действие всех предыдущих параметров --where, в результате чего соответствующие переменные конфигурации больше не будут переопределяться.

--if-exists=<action>

--no-if-exists

Указать, какое действие выполнять, если во входных данных уже есть хотя бы одна строка-трейлер с таким же <key>. Значение, заданное с помощью --if-exists, переопределяет trailer.ifExists и все применимые переменные конфигурации trailer.<key-alias>.ifExists и применяется ко всем параметрам --trailer до следующего вхождения --if-exists или --no-if-exists. Возможные действия: addIfDifferent, addIfDifferentNeighbor, add, replace и doNothing.

Используйте --no-if-exists, чтобы отменить действие всех предыдущих параметров --if-exists, в результате чего соответствующие переменные конфигурации больше не будут переопределяться.

--if-missing=<action>

--no-if-missing

Указать, какое действие выполнять, если во входных данных нет других строк-трейлеров с таким же <key>. Значение, заданное с помощью --if-missing, переопределяет trailer.ifMissing и все применимые переменные конфигурации trailer.<key-alias>.ifMissing и применяется ко всем параметрам --trailer до следующего вхождения --if-missing или --no-if-missing. Возможные действия: doNothing или add.

Используйте --no-if-missing, чтобы отменить действие всех предыдущих параметров --if-missing, в результате чего соответствующие переменные конфигурации больше не будут переопределяться.

--only-trailers

--no-only-trailers

Выводить только строки-трейлеры, без остальных частей входных данных. По умолчанию используется --no-only-trailers.

--only-input

--no-only-input

Выводить только строки-трейлеры, имеющиеся во входных данных; не добавлять строки из командной строки или в результате применения переменных конфигурации trailer.<key-alias>. По умолчанию используется --no-only-input.

--unfold

--no-unfold

Если значение строки-трейлера занимает несколько строк (то есть оно «свернуто»), преобразовать его в одну строку. По умолчанию используется --no-unfold.

--parse

Удобный псевдоним для --only-trailers --only-input --unfold. Он позволяет проще вывести только строки-трейлеры из входных данных без изменения под влиянием параметров командной строки или переменных конфигурации, а также получить пригодный для машинной обработки вывод с помощью --unfold.

У этого псевдонима нет псевдонима для отмены его действия.

--divider

--no-divider

Считать --- концом сообщения коммита. Это значение используется по умолчанию. Используйте --no-divider, если известно, что входные данные содержат только само сообщение коммита (а не электронное письмо или вывод git-format-patch[1]).

Переменные конфигурации

Весь текст ниже этой строки в данном разделе выборочно включен из документации git-config[1]. Содержимое совпадает с приведенным там:

trailer.separators

Этот параметр определяет символы, распознаваемые как разделители строк-трейлеров. По умолчанию разделителем строки-трейлера считается только :, однако = всегда принимается в командной строке для совместимости с другими командами git.

Первый символ, указанный этим параметром, будет символом разделителя по умолчанию, если для этой строки-трейлера в конфигурации не задан другой разделитель.

Например, если значение этого параметра — %=$, строками-трейлерами будут считаться только строки формата <key><sep><value>, в которых <sep> содержит %, = или $, а после него следуют пробелы. Символ % будет использоваться как разделитель по умолчанию, поэтому строки-трейлеры будут выглядеть так: <key>% <value> (между ключом и значением будет один знак процента и один пробел).

trailer.where

Этот параметр определяет, куда будет добавлена новая строка-трейлер.

Возможные значения: end (значение по умолчанию), start, after или before.

Если указано end, каждая новая строка-трейлер будет добавлена в конец имеющихся строк-трейлеров.

Если указано start, каждая новая строка-трейлер будет добавлена в начало, а не в конец имеющихся строк-трейлеров.

Если указано after, каждая новая строка-трейлер будет добавлена сразу после последней строки-трейлера с таким же <key>.

Если указано before, каждая новая строка-трейлер будет добавлена сразу перед первой строкой-трейлером с таким же <key>.

trailer.ifexists

Этот параметр позволяет выбрать действие, которое будет выполняться, если во входных данных уже есть хотя бы одна строка-трейлер с таким же <key>.

Допустимые значения этого параметра: addIfDifferentNeighbor (значение по умолчанию), addIfDifferent, add, replace или doNothing.

При значении addIfDifferentNeighbor новая строка-трейлер будет добавлена, только если выше или ниже строки, куда она будет помещена, нет строки-трейлера с такой же парой (<key>, <value>).

При значении addIfDifferent новая строка-трейлер будет добавлена, только если во входных данных еще нет строки-трейлера с такой же парой (<key>, <value>).

При значении add новая строка-трейлер будет добавлена, даже если во входных данных уже есть строки-трейлеры с такой же парой (<key>, <value>).

При значении replace имеющаяся строка-трейлер с таким же <key> будет удалена, а новая строка-трейлер добавлена. Удаляется ближайшая (с таким же <key>) к месту добавления новой строки-трейлер.

При значении doNothing ничего не произойдет: новая строка-трейлер не будет добавлена, если во входных данных уже есть строка-трейлер с таким же <key>.

trailer.ifmissing

Этот параметр позволяет выбрать действие, которое будет выполняться, если во входных данных еще нет строки-трейлера с таким же <key>.

Допустимые значения этого параметра: add (значение по умолчанию) и doNothing.

При значении add будет добавлена новая строка-трейлер.

При значении doNothing ничего не произойдет.

trailer.<key-alias>.key

Задает <key-alias> для <key>. <key-alias> должен быть префиксом (регистр не имеет значения) <key>. Например, в git config trailer.ack.key "Acked-by" Acked-by — это <key>, а ack — это <key-alias>. Эта настройка позволяет использовать в командной строке сокращенный вызов --trailer "ack:..." с псевдонимом «ack» <key-alias> вместо более длинного --trailer "Acked-by:...".

В конце <key> может находиться разделитель, за которым могут следовать пробелы. По умолчанию допустим только разделитель :, но его можно изменить с помощью переменной конфигурации trailer.separators.

Если в ключе есть разделитель, он переопределяет разделитель по умолчанию при добавлении строки-трейлера.

trailer.<key-alias>.where

Этот параметр принимает те же значения, что и переменная конфигурации trailer.where, и переопределяет заданное ею значение для строк-трейлеров с указанным <key-alias>.

trailer.<key-alias>.ifexists

Этот параметр принимает те же значения, что и переменная конфигурации trailer.ifexists, и переопределяет заданное ею значение для строк-трейлеров с указанным <key-alias>.

trailer.<key-alias>.ifmissing

Этот параметр принимает те же значения, что и переменная конфигурации trailer.ifmissing, и переопределяет заданное ею значение для строк-трейлеров с указанным <key-alias>.

trailer.<key-alias>.command

Устарел; вместо него используйте trailer.<key-alias>.cmd. Этот параметр работает так же, как trailer.<key-alias>.cmd, за исключением того, что указанной команде не передается аргумент. Вместо этого первое вхождение подстроки $ARG заменяется на <value>, которое было бы передано в качестве аргумента.

Обратите внимание, что $ARG в команде пользователя заменяется только один раз, а исходный способ замены $ARG небезопасен.

Если для одного и того же <key-alias> заданы оба параметра — trailer.<key-alias>.cmd и trailer.<key-alias>.command, — используется trailer.<key-alias>.cmd, а trailer.<key-alias>.command игнорируется.

trailer.<key-alias>.cmd

Этот параметр позволяет указать команду оболочки, которая будет вызвана один раз для автоматического добавления строки-трейлера с указанным <key-alias>, а затем будет вызываться каждый раз, когда для изменения <value> создаваемой этим параметром строки-трейлера задается аргумент --trailer <key-alias>=<value>.

При первом вызове указанной команды для добавления строки-трейлера с заданным <key-alias> она работает так, как если бы в начале git-interpret-trailers[1] был добавлен специальный аргумент --trailer <key-alias>=<value>, где <value> — это стандартный вывод команды без начальных и конечных пробельных символов.

Если в командной строке также переданы аргументы --trailer <key-alias>=<value>, команда вызывается повторно для каждого из этих аргументов с тем же <key-alias>. Часть <value> этих аргументов, если она есть, передается команде в качестве первого аргумента. Таким образом, команда может сформировать <value>, вычисленное на основе <value>, переданного в аргументе --trailer <key-alias>=<value>.

Примеры

Настройте строку-трейлер sign с ключом Signed-off-by, а затем добавьте две такие строки-трейлеры в файл сообщения коммита:

$ 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>

Используйте параметр --in-place, чтобы отредактировать файл сообщения коммита на месте:

$ 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>

Извлеките последний коммит в виде патча и добавьте к нему строки-трейлеры Cc и Reviewed-by:

$ 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

Настройте строку-трейлер sign с командой для автоматического добавления «Signed-off-by: » с информацией об авторе, только если строки «Signed-off-by: » еще нет, и посмотрите, как это работает:

$ 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>

Настройте строку-трейлер fix с ключом, содержащим символ # без пробела после него, и посмотрите, как это работает:
```
$ git config trailer.separators ":#"
$ git config trailer.fix.key "Fix #"
$ echo "subject" | git interpret-trailers --trailer fix=42
subject

Fix #42
```

Настройте строку-трейлер help с командой, использующей скрипт glog-find-author, который ищет в журнале git репозитория указанную идентификационную информацию автора, и посмотрите, как это работает:

$ 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>

Настройте строку-трейлер ref с командой, использующей скрипт glog-grep для поиска в журнале git репозитория последнего подходящего коммита, и посмотрите, как это работает:

$ 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)

Настройте строку-трейлер see с командой для отображения темы связанного коммита и посмотрите, как это работает:

$ 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)

Настройте шаблон коммита с несколькими строками-трейлерами с пустыми значениями (используя sed для отображения и сохранения конечных пробелов в строках-трейлерах), затем настройте перехватчик commit-msg, который использует git-interpret-trailers(1) для удаления строк-трейлеров с пустыми значениями и добавления строки-трейлера git-version:
```
$ 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
```

См. также

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

© 2005–2026 Linus Torvalds and others
Licensed under the GNU General Public License version 2.
https://git-scm.com/docs/git-interpret-trailers