Git теги: создание, просмотр и публикация версий
Теги в Git — это именованные указатели на конкретные коммиты. Используются для маркировки релизов (v1.0, v2.3.1). В отличие от веток, теги не перемещаются — они всегда указывают на один и тот же коммит.
Два типа тегов #
Легковесный тег (lightweight) — просто именованный указатель на коммит:
# Создать легковесный тег
git tag v1.0
# На конкретный коммит
git tag v1.0 a1b2c3d
Аннотированный тег (annotated) — объект Git с метаданными:
# Создать аннотированный тег
git tag -a v1.0 -m "Release version 1.0"
# Аннотированный тег хранит:
# - Имя создателя тега
# - Email
# - Дату создания
# - Сообщение (тег-сообщение, не сообщение коммита)
# - GPG подпись (опционально)
Когда использовать:
- Аннотированные теги — для публичных релизов (содержат метаданные)
- Легковесные теги — для временных или внутренних меток
Какой формат тега использовать для релиза #
Стандарт отрасли — семантическое версионирование с префиксом v:
v1.2.0 ← правильно: v + MAJOR.MINOR.PATCH
1.2.0 ← допустимо, но без v менее распространено
version_new ← неправильно (неинформативно)
tag_final ← неправильно (не содержит версию)
release_1.2 ← неправильно (нестандартный формат)
Для релиза версии 1.2.0 правильный тег: v1.2.0
Почему именно такой формат:
v— явный признак версии, отличает от других тегов1.2.0— три числа: мажорная.минорная.патч (semver)- Машиночитаемо: инструменты (GitHub Releases, npm, cargo) автоматически распознают semver-теги
# Правильный тег для релиза 1.2.0
git tag -a v1.2.0 -m "Release 1.2.0: add export feature"
git push origin v1.2.0
Создание тегов #
# Аннотированный тег текущего коммита
git tag -a v2.0.0 -m "Release 2.0.0: new authentication system"
# Аннотированный тег конкретного коммита
git tag -a v1.5.0 a1b2c3d -m "Hotfix release 1.5.0"
# Легковесный тег
git tag v2.0.0-beta
# Тег с GPG подписью
git tag -s v2.0.0 -m "Signed release 2.0.0"
# Перезаписать существующий тег (опасно!)
git tag -f v2.0.0 HEAD
Просмотр тегов #
# Список всех тегов
git tag
# Список с фильтрацией
git tag -l "v1.*"
# v1.0
# v1.1
# v1.2.1
# Подробная информация о теге
git show v1.0
# tag v1.0
# Tagger: John Doe <[email protected]>
# Date: Mon Mar 10 12:00:00 2025 +0300
#
# Release version 1.0
#
# commit a1b2c3d...
# Author: ...
# Хеш коммита под тегом
git rev-parse v1.0
# Теги на конкретном коммите
git tag --points-at HEAD
git tag --points-at a1b2c3d
Семантическое версионирование (semver) #
Общепринятый формат версий MAJOR.MINOR.PATCH:
v2.5.1:
2 — MAJOR: несовместимые изменения API
5 — MINOR: новые функции, обратно совместимые
1 — PATCH: исправления ошибок
Предрелизные версии:
v3.0.0-alpha.1
v3.0.0-beta.2
v3.0.0-rc.1
Примеры тегов:
git tag -a v1.0.0 -m "Initial stable release"
git tag -a v1.1.0 -m "Add user profiles"
git tag -a v1.1.1 -m "Fix login bug"
git tag -a v2.0.0 -m "BREAKING: new API format"
Просмотр аннотации тега #
# Вывести полную аннотацию аннотированного тега
git show v1.0.0
# tag v1.0.0
# Tagger: Иван Иванов <[email protected]>
# Date: Mon Jan 15 10:00:00 2024 +0300
#
# Release 1.0.0: первый стабильный релиз
#
# commit abc1234...
# Только сообщение тега (без diff)
git tag -v v1.0.0 # GPG-верификация + аннотация
# Короткая информация
git for-each-ref refs/tags/v1.0.0 --format="%(taggerdate) %(subject)"
# Последний тег доступный из HEAD
git describe --tags
# v1.0.0-3-gabc1234 (тег + 3 коммита сверху + хеш)
# Ближайший тег
git describe --tags --abbrev=0
# v1.0.0
Отправка тегов на remote #
По умолчанию git push не отправляет теги:
# Отправить один тег
git push origin v1.0
# Отправить все теги
git push origin --tags
# Отправить только аннотированные теги (не легковесные)
git push origin --follow-tags
Клонирование конкретного тега #
Иногда нужно получить репозиторий именно в состоянии определённого релиза — без всей истории и без последних незарелизенных изменений.
# Клонировать репозиторий на конкретный тег
git clone --branch v1.0.0 [email protected]:user/project.git
# Клонировать тег с shallow clone (только один коммит — быстро!)
git clone --branch v1.0.0 --depth 1 [email protected]:user/project.git
# Клонировать в конкретную папку
git clone --branch v2.3.1 https://github.com/user/project.git project-v2.3.1
При таком клонировании репозиторий будет в состоянии detached HEAD — именно на том коммите, на который указывает тег. Это нормально для изучения или сборки релиза.
# Посмотреть на каком теге находимся
git describe --tags
# v1.0.0
# Создать ветку от тега если нужно внести изменения
git switch -c hotfix/v1.0.0
Получение тегов #
# При клонировании теги получаются автоматически
git clone [email protected]:user/project.git
# Получить новые теги из remote
git fetch --tags
# Получить теги и обновить ветки
git fetch origin
Удаление тегов #
# Удалить локальный тег
git tag -d v1.0
# Удалить тег на remote
git push origin --delete v1.0
# или
git push origin :refs/tags/v1.0
# Удалить несколько тегов
git tag -d v1.0 v1.1 v1.2
Checkout по тегу #
# Переключиться на состояние репозитория в момент тега
git checkout v1.0
# ВНИМАНИЕ: это создаёт detached HEAD
# Создать ветку от тега для внесения изменений
git switch -c hotfix/v1.0 v1.0
# Посмотреть файлы на момент тега (без переключения)
git show v1.0:README.md
git ls-tree v1.0
Практические примеры #
# Подготовить релиз
git switch main
git pull origin main
# Создать тег релиза
git tag -a v3.1.0 -m "Version 3.1.0: add export feature"
# Отправить тег
git push origin v3.1.0
# или все теги:
git push origin --follow-tags
# Посмотреть историю релизов
git log --oneline --decorate | grep "tag:"
# Разница между двумя релизами
git diff v1.0..v2.0
# Количество коммитов между релизами
git log v1.0..v2.0 --oneline | wc -l
# Changelog между тегами
git log v1.0..v2.0 --pretty=format:"- %s" > CHANGELOG.md
Часто задаваемые вопросы #
Чем тег отличается от ветки? Ветка — подвижный указатель (перемещается при каждом коммите). Тег — неподвижный (всегда указывает на один коммит). Тег обычно маркирует конкретный момент в истории.
Почему git push не отправляет теги? По умолчанию. Используйте git push --tags для всех тегов или git push origin v1.0 для конкретного.
Можно ли изменить аннотацию тега? Не напрямую — нужно удалить тег и создать заново: git tag -d v1.0 && git tag -a v1.0 -m "New message". Если тег уже на remote — нужен force push (изменение тегов нарушает принципы immutability).
Как получить список тегов отсортированный по версии? git tag -l --sort=version:refname "v*" — сортирует по semver версии.
Что такое –follow-tags? git push --follow-tags отправляет только аннотированные теги, которые доступны (reachable) из отправляемых коммитов. Это рекомендуемый способ — не отправляет временные/ненужные теги.
Заключение #
Теги — способ маркировки релизов в Git. Аннотированные теги (git tag -a v1.0 -m "...") предпочтительны для релизов — содержат метаданные. Отправка на remote: git push origin --follow-tags. Используйте семантическое версионирование (MAJOR.MINOR.PATCH). Для просмотра истории тегов и коммитов — git log.