Русский ▾ Topics ▾ Latest version ▾ git-tag last updated in 2.52.0

НАЗВАНИЕ

git-tag — Создание, вывод списка, удаление или проверка меток

ОБЗОР

git tag [-a | -s | -u <id-ключа>] [-f] [-m <сообщение> | -F <файл>] [-e]
	[(--trailer <лексема>[(=|:)<значение>])…​]
	<имя-метки> [<коммит> | <объект>]
git tag -d <имя-метки>…​
git tag [-n[<число>]] -l [--contains <коммит>] [--no-contains <коммит>]
	[--points-at <объект>] [--column[=<параметры>] | --no-column]
	[--create-reflog] [--sort=<ключ>] [--format=<формат>]
	[--merged <коммит>] [--no-merged <коммит>] [<шаблон>…​]
git tag -v [--format=<формат>] <имя-метки>…​

ОПИСАНИЕ

Добавляет ссылку на метку в refs/tags/, если только -d/-l/-v не заданы для удаления, вывода списка или проверки меток.

Если не указан -f, указанная метка не должна существовать.

Если передан один из параметров -a, -s или -u <id-ключа>, команда создаёт объект метка и требует сообщение метки. Если не указаны -m <сообщение> или -F <файл>, запускается редактор, чтобы пользователь ввёл сообщение метки.

Если указаны -m <сообщение>, -F <файл> или --trailer <лексема>[=<значение>], а -a, -s и -u <id-ключа> отсутствуют, подразумевается -a.

В противном случае создаётся ссылка на метку, которая указывает непосредственно на заданный объект (т.е. легковесная метка).

Криптографически подписанный объект метки будет создан при использовании -s или -u <id-ключа>. Внутренний механизм подписи (GPG, X.509, SSH и т.д.) управляется переменной конфигурации gpg.format, по умолчанию OpenPGP. Когда -u <id-ключа> не используется, для поиска ключа подписи используется идентификатор коммиттера для текущего пользователя. Переменная конфигурации gpg.program используется для указания пользовательского двоичного файла подписи.

Объекты меток (созданные с помощью -a, -s или -u) называются «аннотированными» метками; они содержат дату создания, имя и email автора метки, сообщение метки и необязательную криптографическую подпись. Тогда как «легковесная» метка — это просто имя для объекта (обычно объекта-коммита).

Аннотированные метки предназначены для выпусков, в то время как легковесные метки предназначены для частных или временных меток объектов. По этой причине некоторые команды git для именования объектов (например, git describe) по умолчанию игнорируют легковесные метки.

ПАРАМЕТРЫ

-a
--annotate

Создать неподписанный аннотированный объект метки

-s
--sign

Создать криптографически подписанную метку, используя ключ подписи по умолчанию. Используемый внутренний механизм подписи зависит от переменной конфигурации gpg.format. Ключ по умолчанию определяется внутренним механизмом. Для GPG он основан на адресе электронной почты коммиттера, а для SSH это может быть определённый файл ключа или идентификатор агента. См. git-config[1].

--no-sign

Переопределяет переменную конфигурации tag.gpgSign, которая установлена для принудительного подписания каждой метки.

-u <id-ключа>
--local-user=<id-ключа>

Создать криптографически подписанную метку, используя указанный ключ. Формат <id-ключа> и используемый внутренний механизм зависят от переменной конфигурации gpg.format. См. git-config[1].

-f
--force

Заменить существующую метку с указанным именем (вместо ошибки)

-d
--delete

Удалить существующие метки с указанными именами.

-v
--verify

Проверить криптографическую подпись указанных меток.

-n<число>

<число> указывает, сколько строк из аннотации (если они есть) выводится при использовании -l. Подразумевает --list.

По умолчанию строки аннотации не выводятся. Если -n не указано число, выводится только первая строка. Если метка не аннотирована, вместо неё отображается сообщение коммита.

-l
--list

Вывести список меток. С необязательными <шаблон>..., например, git tag --list v-*', вывести только метки, соответствующие шаблону(ам).

Запуск git tag без аргументов также выводит список всех меток. Шаблон — это wildcard оболочки (т.е. сопоставление с помощью fnmatch(3)). Может быть задано несколько шаблонов; если любой из них соответствует, метка показывается.

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

--sort=<ключ>

Сортировать на основе заданного ключа. Добавьте префикс - для сортировки по убыванию значения. Вы можете использовать опцию --sort=<ключ> несколько раз, и в этом случае последний <ключ> становится основным. Также поддерживается "version:refname" или "v:refname" (имена меток рассматриваются как версии). На порядок сортировки "version:refname" также может влиять переменная конфигурации "versionsort.suffix". Поддерживаются те же ключи, что и в git for-each-ref. Порядок сортировки по умолчанию соответствует значению, заданному для переменной tag.sort, если она существует, или лексикографическому порядку. См. git-config[1].

--color[=<когда>]

Учитывает любые цвета, указанные в опции --format. Поле <когда> должно быть одним из always, never или auto (если <когда> отсутствует, вести себя так, как если бы было указано always).

-i
--ignore-case

Сортировка и фильтрация меток не учитывают регистр.

--omit-empty

Если после форматирования ссылки, согласно формату она расширяется до пустой строки, не выводить символ перехода на новую строку.

--column[=<параметры>]
--no-column

Отображать список меток по столбцам. См. синтаксис параметров в переменной конфигурации column.tag. --column и --no-column без параметров эквивалентны always и never соответственно.

Этот параметр применим только при выводе списка меток без строк аннотации.

--contains [<коммит>]

Вывести только те метки, которые содержат <коммит> (HEAD, если не указан). Подразумевает --list.

--no-contains [<коммит>]

Вывести только те метки, которые не содержат <коммит> (HEAD, если не указан). Подразумевает --list.

--merged [<коммит>]

Вывести только те метки, чьи коммиты достижимы из <коммит> (HEAD, если не указан).

--no-merged [<коммит>]

Вывести только те метки, чьи коммиты не достижимы из <коммит> (HEAD, если не указан).

--points-at [<объект>]

Вывести только метки, связанные с <объектом> (HEAD, если не указан). Подразумевает --list.

-m <сообщение>
--message=<сообщение>

Использовать <сообщение> (вместо приглашения на ввод). Если указано несколько опций -m, их значения объединяются как отдельные абзацы. Подразумевает -a, если не указаны ни -a, ни -s, ни -u <id-ключа>.

-F <файл>
--file=<файл>

Взять сообщение метки из <файла>. Используйте - для чтения сообщения из стандартного ввода. Подразумевает -a, если не указаны ни -a, ни -s, ни -u <id-ключа>.

--trailer <лексема>[(=|:)<значение>]

Указать пару (<токен>,<значение>), которая должна быть применена как завершитель. (например, git tag --trailer "Пользовательский-Ключ: значение" добавит завершитель "Пользовательский-Ключ" в сообщение метки.) Переменные конфигурации trailer.* (git-interpret-trailers[1]) можно использовать для определения того, опускается ли дублирующийся завершитель, где в последовательности завершителей будет появляться каждый завершитель, и других деталей. Завершители могут быть извлечены в git tag --list с использованием заполнителя --format="%(trailers)".

-e
--edit

Разрешить дальнейшее редактирование сообщения, взятого из файла с -F и из командной строки с -m.

--cleanup=<режим>

Устанавливает, как очищается сообщение метки. <режим> может быть одним из verbatim, whitespace и strip. Режим strip используется по умолчанию. Режим verbatim вообще не изменяет сообщение, whitespace удаляет только начальные/конечные строки с пробелами, а strip удаляет как пробелы, так и комментарии.

--create-reflog

Создать журнал ссылок (reflog) для метки. Чтобы глобально включить журналы ссылок для меток, см. core.logAllRefUpdates в git-config[1]. Отрицательная форма --no-create-reflog переопределяет только более ранний --create-reflog, но в настоящее время не отменяет настройку core.logAllRefUpdates.

--format=<формат>

Строка, которая интерполирует %(имя-поля) из отображаемой ссылки на метку и объекта, на который она указывает. Формат такой же, как в git-for-each-ref[1]. Если не указано, по умолчанию используется %(refname:strip=2).

<имя-метки>

Имя метки для создания, удаления или описания. Новое имя метки должно проходить все проверки, определённые git-check-ref-format[1]. Некоторые из этих проверок могут ограничивать символы, разрешённые в имени метки.

<коммит>
<объект>

Объект, на который будет ссылаться новая метка, обычно коммит. По умолчанию HEAD.

КОНФИГУРАЦИЯ

По умолчанию git tag в режиме подписи по умолчанию (-s) будет использовать вашу идентификацию коммиттера (в форме Ваше Имя <ваш@email.адрес>) для поиска ключа. Если вы хотите использовать другой ключ по умолчанию, вы можете указать его в конфигурации репозитория следующим образом:

[user]
    signingKey = <id-ключа>

Внутренний механизм подписи можно выбрать с помощью переменной конфигурации gpg.format, которая по умолчанию имеет значение openpgp. Список других поддерживаемых форматов см. в git-config[1].

Путь к программе, используемой для каждого внутреннего механизма подписи, можно указать с помощью переменной конфигурации gpg.<формат>.program. Для внутреннего механизма openpgp gpg.program можно использовать как синоним gpg.openpgp.program. Подробности см. в git-config[1].

pager.tag учитывается только при выводе списка меток, т.е. когда используется или подразумевается -l. По умолчанию используется постраничный вывод.

См. git-config[1] для получения более подробной информации и других переменных конфигурации.

ОБСУЖДЕНИЕ

О повторной маркировке

Что следует делать, если вы пометили не тот коммит и хотите перемаркировать?

Если вы ничего не отправляли наружу, просто перемаркируйте. Используйте -f, чтобы заменить старую. И всё.

Но если вы уже отправляли изменения наружу (или другие могут просто читать ваш репозиторий напрямую), то другие уже видели старую метку. В этом случае вы можете сделать одно из двух:

  1. Разумный поступок. Просто признайте, что ошиблись, и используйте другое имя. Другие уже видели одно имя метки, и если вы сохраните то же имя, может возникнуть ситуация, когда у двух человек будет «версия X», но на самом деле у них будут разные «X». Так что просто назовите её «X.1» и покончите с этим.

  2. Безумный поступок. Вы действительно хотите назвать новую версию тоже «X», даже если другие уже видели старую. Так что просто снова используйте git tag -f, как если бы вы ещё не публиковали старую.

Однако Git не (и не должен) изменять метки за спиной пользователей. Поэтому, если кто-то уже получил старую метку, выполнение git pull вашего дерева не должно просто заставить их перезаписать старую.

Если кто-то получил от вас метку выпуска, вы не можете просто изменить для них метку, обновив свою собственную. Это большая проблема безопасности, поскольку люди ДОЛЖНЫ иметь возможность доверять своим именам меток. Если вы действительно хотите сделать безумную вещь, вам нужно просто признаться в этом и сказать людям, что вы ошиблись. Вы можете сделать это, сделав очень публичное объявление:

Итак, я ошибся и отправил более раннюю версию, помеченную как X. Затем
я кое-что исправил и снова пометил *исправленное* дерево как X.

Если вы получили неправильную метку и хотите новую, пожалуйста, удалите
старую и получите новую, выполнив:

	git tag -d X
	git fetch origin tag X

чтобы получить мою обновлённую метку.

Вы можете проверить, какая у вас метка, выполнив

	git rev-parse X

которая должна вернуть 0123456789abcdef.., если у вас новая версия.

Извините за доставленные неудобства.

Это кажется немного сложным? Так и должно быть. Не может быть правильным просто «исправить» это автоматически. Люди должны знать, что их метки могли быть изменены.

Об автоматическом отслеживании

Если вы отслеживаете чужое дерево, вы, скорее всего, используете отслеживаемые внешние ветки (например, refs/remotes/origin/master). Обычно вы хотите получать метки с другой стороны.

С другой стороны, если вы получаете данные, потому что хотите выполнить однократное слияние от кого-то другого, вы обычно не хотите получать оттуда метки. Это чаще случается с людьми, близкими к верхнему уровню, но не ограничиваясь ими. Обычные смертные при извлечении (pull) друг от друга не обязательно хотят автоматически получать частные якорные метки от другого человека.

Часто сообщения «please pull» в списках рассылки предоставляют только две части информации: URL-адрес репозитория и имя ветки; это предназначено для лёгкого копирования и вставки в конец командной строки git fetch:

Линус, пожалуйста, извлеки (pull) из

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

чтобы получить следующие обновления...

становится:

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

В таком случае вы не хотите автоматически отслеживать метки другого человека.

Одним из важных аспектов Git является его распределённая природа, что в значительной степени означает отсутствие в системе присущих ей «вышестоящих» (upstream) или «нижестоящих» (downstream) репозиториев. На первый взгляд, приведённый выше пример может показаться указанием на то, что пространство имён меток принадлежит верхнему эшелону людей и что метки текут только вниз, но это не так. Это лишь показывает, что шаблон использования определяет, кто заинтересован в чьих метках.

Однократное извлечение (one-shot pull) является признаком того, что история коммитов пересекает границу между одним кругом людей (например, «люди, которые в первую очередь интересуются сетевой частью ядра»), у которых может быть свой собственный набор меток (например, «это третий кандидат на выпуск от сетевой группы, предлагаемый для общего использования с выпуском 2.6.21»), и другим кругом людей (например, «люди, которые интегрируют различные улучшения подсистем»). Последних обычно не интересуют детальные метки, используемые внутри первой группы (именно это означает «внутренние»). Вот почему в этом случае желательно не отслеживать метки автоматически.

Вполне возможно, что среди сетевых специалистов они могут захотеть обмениваться метками внутри своей группы, но в этом рабочем процессе они, скорее всего, отслеживают прогресс друг друга с помощью отслеживаемых внешних веток. И снова, эвристика автоматического отслеживания таких меток — это хорошая вещь.

О датировании меток задним числом

Если вы импортировали некоторые изменения из другой VCS и хотели бы добавить метки для основных выпусков вашей работы, полезно иметь возможность указать дату для встраивания в объект метки; такие данные в объекте метки влияют, например, на порядок меток в интерфейсе gitweb.

Чтобы установить дату, используемую в будущих объектах меток, установите переменную окружения GIT_COMMITTER_DATE (см. последующее обсуждение возможных значений; наиболее распространённая форма — "ГГГГ-ММ-ДД ЧЧ:ММ").

Например:

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

ФОРМАТЫ ДАТЫ

Переменные среды GIT_AUTHOR_DATE и GIT_COMMITTER_DATE поддерживают следующие форматы дат:

Внутренний формат Git

<unix-timestamp> <time-zone-offset>, где <unix-timestamp> — количество секунд, прошедших с эпохи UNIX (00:00:00 UTC 1 января 1970 года). А <time-zone-offset> является положительным или отрицательным смещением относительно UTC. Например, для CET (центральноевропейское время которое на 1 час опережает UTC) значение будет +0100.

RFC 2822

Стандартный формат даты, описанный RFC 2822, например, Thu, 07 Apr 2005 22:13:13 +0200.

ISO 8601

Время и дата, согласно стандарту ISO 8601, например, 2005-04-07T22:13:13'. Принимается также пробел вместо `Т. Дробные доли секунды будут отброшены, например ‘2005-04-07T22:13:13.019’ будет восприниматься как ‘2005-04-07T22:13:13’.

Note
 Кроме того, часть представляющая дату принимается в следующих форматах: ГГГГ.ММ.ДД, ММ/ДД/ГГГГ и ДД.ММ.ГГГГ.

ФАЙЛЫ

$GIT_DIR/TAG_EDITMSG

Этот файл содержит сообщение создаваемой аннотированной метки. Если git tag завершается с ошибкой до создания аннотированной метки, то сообщение метки, предоставленное пользователем в сеансе редактора, будет доступно в этом файле, но может быть перезаписано следующим вызовом git tag.

КОНФИГУРАЦИЯ

Дальнейшее содержание этого раздела, повторяет то, что может быть найдено в git-config[1]:

tag.forceSignAnnotated

Логическое значение, указывающее, должны ли создаваемые аннотированные метки подписываться с помощью GPG. Если в командной строке указан --annotate, он имеет приоритет над этой опцией.

tag.sort

Эта переменная управляет порядком сортировки меток при отображении git-tag. Если не указана опция --sort=<значение>, значение этой переменной будет использоваться по умолчанию.

tag.gpgSign

Логическое значение, указывающее, должны ли все метки подписываться с помощью GPG. Использование этой опции при выполнении в автоматизированном скрипте может привести к подписанию большого количества меток. Поэтому удобно использовать агент, чтобы избежать многократного ввода вашей GPG-фразы. Обратите внимание, что эта опция не влияет на поведение подписания меток, включённое опциями -u <id-ключа> или --local-user=<id-ключа>.

ЗАМЕТКИ

При комбинировании нескольких фильтров --contains и --no-contains отображаются только ссылки, которые содержат хотя бы один из коммитов --contains и не содержат ни одного из коммитов --no-contains.

При комбинировании нескольких фильтров --merged и --no-merged отображаются только ссылки, которые достижимы из хотя бы одного из коммитов --merged и не достижимы из ни одного из коммитов --no-merged.

СМ. ТАКЖЕ

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

GIT

Является частью пакета git[1]