git-tag

Имя

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

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

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

Описание

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

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

Если передан один из параметров -a, -s или -u <key-id>, команда создаёт объект tag и требует сообщение тега. Если не указаны -m <msg> или -F <file>, запускается редактор, в котором пользователь может ввести сообщение тега.

Если указаны -m <msg>, -F <file> или --trailer <token>[=<value>], а -a, -s и -u <key-id> отсутствуют, подразумевается -a.

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

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

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

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

Параметры

-a

--annotate

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

-s

--sign

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

--no-sign

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

-u <key-id>

--local-user=<key-id>

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

-f

--force

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

-d

--delete

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

-v

--verify

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

-n<num>

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

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

-l

--list

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

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

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

--sort=<key>

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

--color[=<when>]

Использовать цвета, заданные параметром --format. Поле <when> должно иметь одно из значений: always, never или auto (если <when> отсутствует, ведёт себя так, как если бы было указано always).

-i

--ignore-case

Сортировать и фильтровать теги без учёта регистра.

--omit-empty

Не выводить символ новой строки после форматированных ссылок, если результат форматирования — пустая строка.

--column[=<options>]

--no-column

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

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

--contains [<commit>]

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

--no-contains [<commit>]

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

--merged [<commit>]

Выводить только теги, коммиты которых доступны из <commit> (если параметр не указан, используется HEAD).

--no-merged [<commit>]

Выводить только теги, коммиты которых недоступны из <commit> (если параметр не указан, используется HEAD).

--points-at [<object>]

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

-m <msg>

--message=<msg>

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

-F <file>

--file=<file>

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

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

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

-e

--edit

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

--cleanup=<mode>

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

--create-reflog

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

--format=<format>

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

<tagname>

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

<commit>

<object>

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

Настройка

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

[user]
    signingKey = <key-id>

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

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

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

Дополнительные сведения и описание других переменных конфигурации см. в git-config[1].

Обсуждение

Повторное назначение тегов

Что делать, если вы пометили не тот коммит и хотите назначить тег заново?

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

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

Разумный способ. Признайте свою ошибку и используйте другое имя. Другие уже видели одно имя тега, и если вы сохраните то же имя, может возникнуть ситуация, когда у двух людей будет «версия X», но на самом деле у них будут different «X». Просто назовите её «X.1» — и готово.
Безумный способ. Вы действительно хотите назвать новую версию «X», хотя even though другие уже видели старую. Просто снова используйте git tag -f, как будто вы ещё не публиковали старую версию.

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

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

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.

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

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

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

С другой стороны, если вы выполняете выборку, чтобы один раз слить изменения другого пользователя, обычно вам не нужны оттуда теги. Такое чаще встречается у пользователей, работающих ближе к вершине проекта, но не ограничивается ими. Обычным пользователям, получающим изменения друг от друга, не обязательно нужно автоматически получать частные опорные теги другого человека.

Часто в сообщениях «прошу выполнить выборку» в списке рассылки приводятся только две сведения: URL репозитория и имя ветки; это сделано для того, чтобы их можно было легко скопировать в конец командной строки git fetch:

Linus, please pull from

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

to get the following updates...

превращается в:

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

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

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

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

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

Установка более ранних дат тегов

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

Чтобы задать дату для будущих объектов тегов, установите переменную окружения GIT_COMMITTER_DATE (см. ниже описание допустимых значений; наиболее распространённый формат — «YYYY-MM-DD HH:MM»).

Например:

$ 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. <time-zone-offset> — положительное или отрицательное смещение относительно UTC. Например, CET (на 1 час опережает UTC) — это +0100.

Безопаснее добавлять в начало <unix-timestamp> префикс @ (например, @0 +0000), чтобы Git интерпретировал значение как необработанную временную метку. Это необходимо для значений меньше 100 000 000 (с числом цифр меньше 9), чтобы избежать путаницы с другими форматами дат, например YYYYMMDD.

RFC 2822

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

ISO 8601

Время и дата, заданные стандартом ISO 8601, например 2005-04-07T22:13:13. Анализатор также принимает вместо символа T пробел. Дробная часть секунды игнорируется: например, 2005-04-07T22:13:13.019 будет интерпретировано как 2005-04-07T22:13:13.

Примечание

Кроме того, часть с датой допускает следующие форматы: YYYY.MM.DD, MM/DD/YYYY и DD.MM.YYYY.

Файлы

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

Настройка

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

tag.forceSignAnnotated: Логическое значение, указывающее, следует ли подписывать созданные аннотированные теги с помощью GPG. Если в командной строке указано --annotate, этот параметр имеет приоритет.
tag.sort: Эта переменная управляет порядком сортировки тегов при отображении с помощью git-tag. Если параметр --sort=<value> не указан, значение этой переменной используется по умолчанию.
tag.gpgSign: Логическое значение, указывающее, следует ли подписывать с помощью GPG все теги. Использование этого параметра при запуске автоматизированного скрипта может привести к подписанию большого количества тегов. Поэтому удобно использовать агент, чтобы не вводить парольную фразу GPG несколько раз. Обратите внимание, что этот параметр не влияет на поведение при подписании тегов, заданное параметрами -u <keyid> или --local-user=<keyid>.

Примечания

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

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

См. также

git-check-ref-format[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-tag