українська мова ▾ Topics ▾ Latest version ▾ git-tag last updated in 2.52.0

НАЗВА

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 <ідентифікатор-ключа>, команда створює об’єкт tag і вимагає введення тексту тегу. Якщо не вказано параметр -m <повідомлення> або -F <файл>, запускається редактор, у якому користувач може ввести текст повідомлення.

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

В іншому випадку створюється посилання на тег, яке вказує безпосередньо на заданий обʼєкт (тобто легкий тег).

Криптографічно підписаний обʼєкт тегу буде створено, якщо використовується -s або -u <ідентифікатор-ключа>. Бекенд підпису (GPG, X.509, SSH тощо) визначається змінною конфігурації gpg.format, зазвичай використовується OpenPGP. Коли -u <ідентифікатор-ключа> не використовується, для пошуку ключа для підпису використовується ідентифікатор комітера поточного користувача. Змінна конфігурації 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

Перелік тегів. За допомогою опції <шаблон>..., наприклад git tag --list “v-*”`, можна вивести лише ті теги, які відповідають заданому шаблону (шаблонам).

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

Цей параметр неявно надається, якщо надано будь-який інший параметр, подібний до списку, такий як --contains. Дивіться документацію для кожного з цих параметрів для отримання детальної інформації.

--sort=<ключ>

Сортування за вказаним ключем. Додайте префікс -, щоб сортувати за спаданням значень. Опцію --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[=<опція>]
--no-column

Показати список тегів у стовпцях. Синтаксис параметрів див. у змінній конфігурації column.tag. Параметри --column та --no-column без додаткових опцій відповідають значенням always та never відповідно.

Цей параметр застосовується лише під час виводу тегів без рядків анотацій.

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

Виводити лише теги, що містять <commit> (HEAD, якщо не вказано). Мається на увазі --list.

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

Виводити лише теги, що не містять <commit> (HEAD, якщо не вказано). Мається на увазі --list.

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

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

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

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

--points-at [<object>]

Виводити лише теги <object> (HEAD, якщо не вказано). Мається на увазі --list.

-m <msg>
--message=<повідомлення>

Використовувати <msg> (замість запиту). Якщо задано кілька опцій -m, їхні значення обʼєднуються в окремі абзаци. Має тьсяна увазі -a, якщо не задано жодної з опцій -a, -s або -u <ідентифікатор-ключа>.

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

Отримати повідомлення тегу з <файлу>. Використовуйте - для зчитування повідомлення зі стандартного вводу. Мається на увазі -a, якщо не вказано жодного з -a, -s або -u <ідентифікатор-ключа>.

--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> може мати один із варіантів: verbatim, whitespace або strip. Режим strip є стандартним. Режим verbatim взагалі не змінює повідомлення, whitespace видаляє лише початкові/заключні пробіли, а strip видаляє як пробіли, так і коментарі.

--create-reflog

Створити reflog для тегу. Щоб увімкнути reflogs для тегів у глобальному масштабі, див. параметр 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) використовує ідентифікатор автора коміту (у форматі Ваше ім’я <ваша@email.address>) для пошуку ключа. Якщо ви хочете використовувати інший ключ як типовий, ви можете вказати його в конфігурації репозиторію таким чином:

[user]
    signingKey = <key-id>

Бекенд підпису можна вибрати за допомогою змінної конфігурації gpg.format, яка типово має значення openpgp. Див. список інших підтримуваних форматів у git-config[1].

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

pager.tag враховується лише під час виводу тегів, тобто коли використовується або мається на увазі -l. Типово використовується pager.

Див. 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» у списку розсилки містять лише два фрагменти інформації: URL-адресу репозиторію та назву гілки; це розроблено для легкого копіювання та вставки в кінці командного рядка git fetch:

Лінусе, будь ласка, витягни з

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

щоб отримати наступні оновлення...

стає:

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

У такому випадку ви не хочете автоматично слідкувати за тегами іншої людини.

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

Одноразове отримання (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. <time-zone-offset> — це додатне або від’ємне зміщення від UTC. Наприклад, CET (який на 1 годину випереджає UTC) дорівнює +0100.

RFC 2822

Стандартний формат дати, як описано в RFC 2822, наприклад, Чт, 07 квітня 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.

Note
 Крім того, частина дати приймається в таких форматах: РРРР.ММ.ДД, ММ/ДД/РРРР та ДД.ММ.РРРР.

ФАЙЛИ

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

GIT

Частина набору git[1]