git-describe

Имя

git-describe — присваивает объекту понятное человеку имя на основе доступной ссылки

Синопсис

git describe [--all] [--tags] [--contains] [--abbrev=<n>] [<commit-ish>…]
git describe [--all] [--tags] [--contains] [--abbrev=<n>] --dirty[=<mark>]
git describe <blob>

Описание

Команда находит самый последний тег, достижимый из коммита. Если тег указывает на этот коммит, отображается только тег. В противном случае к имени тега добавляется количество дополнительных коммитов после помеченного объекта и сокращённое имя объекта самого последнего коммита. В результате получается «понятное человеку» имя объекта, которое также можно использовать, чтобы идентифицировать коммит в других командах Git.

По умолчанию (без --all или --tags) git describe отображает только аннотированные теги. Дополнительную информацию о создании аннотированных тегов см. в параметрах -a и -s команды git-tag[1].

Если указанный объект является blob-объектом, он будет описан как <commit-ish>:<path>, так что blob-объект можно будет найти по пути <path> в <commit-ish>, который сам описывает первый коммит, в котором встречается этот blob-объект, при обратном обходе ревизий от HEAD.

Параметры

<commit-ish>...: Имена объектов commit-ish для описания. Если не указаны, по умолчанию используется HEAD.
--dirty[=<mark>]
--broken[=<mark>]: Описать состояние рабочего дерева. Если рабочее дерево соответствует HEAD, вывод будет таким же, как у git describe HEAD. Если в рабочем дереве есть локальные изменения, к выводу добавляется -dirty. Если репозиторий повреждён и Git не может определить, есть ли локальные изменения, Git завершит работу с ошибкой, если не указан параметр --broken; в этом случае вместо этого добавляется суффикс -broken.
--all: Вместо использования только аннотированных тегов использовать любые ссылки, найденные в пространстве имён refs/. Этот параметр позволяет сопоставлять любые известные ветки, отслеживаемые удалённые ветки или облегчённые теги.
--tags: Вместо использования только аннотированных тегов использовать любые теги, найденные в пространстве имён refs/tags. Этот параметр позволяет сопоставлять облегчённые (неаннотированные) теги.
--contains: Вместо поиска тега, предшествующего коммиту, найти тег, который следует за коммитом и, следовательно, содержит его. Автоматически подразумевает --tags.
--abbrev=<n>: Вместо числа шестнадцатеричных цифр по умолчанию (которое зависит от количества объектов в репозитории и по умолчанию равно 7), используемых в сокращённом имени объекта, использовать <n> цифр или столько цифр, сколько необходимо для получения уникального имени объекта. Значение <n>, равное 0, отключает длинный формат: отображается только ближайший тег.
--candidates=<n>: Вместо рассмотрения только 10 самых последних тегов в качестве кандидатов для описания указанного commit-ish рассмотреть до <n> кандидатов. Увеличение <n> свыше 10 немного увеличит время выполнения, но может дать более точный результат. Значение <n>, равное 0, приведёт к выводу только точных совпадений.
--exact-match: Выводить только точные совпадения (тег непосредственно ссылается на указанный коммит). Это синоним --candidates=0.
--debug: Подробно выводить в stderr информацию об используемой стратегии поиска. Имя тега по-прежнему будет выводиться в stdout.
--long: Всегда выводить длинный формат (тег, количество коммитов и сокращённое имя коммита), даже если имеется совпадение с тегом. Это полезно, если вы хотите видеть части имени объекта коммита в выводе «describe», даже когда рассматриваемый коммит является помеченной тегом версией. Вместо вывода одного лишь имени тега такой коммит будет описан как v1.2-0-gdeadbee (нулевой коммит после тега v1.2, указывающего на объект deadbee…).
--match <pattern>: Рассматривать только теги, соответствующие заданному шаблону glob(7), без префикса «refs/tags/». При использовании с --all также рассматриваются локальные ветки и ссылки на отслеживаемые удалённые ветки, соответствующие шаблону, без префиксов «refs/heads/» и «refs/remotes/» соответственно; ссылки других типов не рассматриваются. При повторном указании параметры добавляются в список шаблонов, и учитываются теги, соответствующие любому из них. Используйте --no-match, чтобы очистить список шаблонов и начать его заново.
--exclude <pattern>: Не рассматривать теги, соответствующие заданному шаблону glob(7), без префикса «refs/tags/». При использовании с --all также не рассматриваются локальные ветки и ссылки на отслеживаемые удалённые ветки, соответствующие шаблону, без префиксов «refs/heads/» и «refs/remotes/» соответственно; ссылки других типов не рассматриваются. При повторном указании параметры добавляются в список шаблонов, и исключаются теги, соответствующие любому из них. Если этот параметр используется вместе с --match, тег будет учитываться, если он соответствует хотя бы одному шаблону --match и не соответствует ни одному шаблону --exclude. Используйте --no-exclude, чтобы очистить список шаблонов и начать его заново.
--always: В качестве запасного варианта показывать уникальное сокращённое имя объекта коммита.
--first-parent: При обнаружении коммита слияния переходить только к коммиту первого родителя. Это полезно, если нужно не сопоставлять теги веток, слитых в историю целевого коммита.

Примеры

Для текущего дерева git.git я получаю примерно следующее:

[torvalds@g5 git]$ git describe parent
v1.0.4-14-g2414721

То есть текущая вершина моей ветки «parent» основана на v1.0.4, но, поскольку после него есть несколько коммитов, describe добавила в конец количество дополнительных коммитов («14») и сокращённое имя самого коммита («2414721»).

Количество дополнительных коммитов — это число коммитов, которые были бы показаны командой git log v1.0.4..parent. Суффикс хеша — это «-g» + однозначное сокращённое имя вершины ветки parent (это было 2414721b194453f058079d897d13c4e377f92dc6). Длина сокращения увеличивается по мере роста репозитория: она определяется на основе приблизительного количества объектов в репозитории и некоторых вычислений, связанных с парадоксом дней рождения; минимальная длина по умолчанию равна 7. Префикс «g» означает «git» и позволяет описывать версию программы с учётом используемой для управления ею системы контроля версий. Это полезно в среде, где люди могут использовать разные системы контроля версий.

Выполнение команды git describe для имени тега просто покажет имя тега:

[torvalds@g5 git]$ git describe v1.0.4
v1.0.4

С параметром --all команда может использовать вершины веток в качестве ссылок, поэтому в выводе также отображается путь ссылки:

[torvalds@g5 git]$ git describe --all --abbrev=4 v1.0.5^2
tags/v1.0.0-21-g975b

[torvalds@g5 git]$ git describe --all --abbrev=4 HEAD^
heads/lt/describe-7-g975b

Если для --abbrev задано значение 0, команду можно использовать для поиска ближайшего имени тега без суффикса:

[torvalds@g5 git]$ git describe --abbrev=0 v1.0.5^2
tags/v1.0.0

Обратите внимание: суффикс, полученный при выполнении этих команд сегодня, может быть длиннее того, который получил Линус, когда выполнял их выше: в вашем репозитории Git могли появиться новые коммиты с именами объектов, начинающимися с 975b, которых тогда ещё не было, и одного суффикса «-g975b» может быть недостаточно, чтобы однозначно различить эти коммиты.

Стратегия поиска

Для каждого указанного commit-ish git describe сначала ищет тег, который указывает именно на этот коммит. Аннотированные теги всегда имеют приоритет над облегченными, а теги с более поздними датами — над тегами с более ранними датами. Если найдено точное совпадение, выводится его имя, и поиск завершается.

Если точное совпадение не найдено, git describe проходит назад по истории коммитов, чтобы найти помеченный тегом коммит-предок. Выводится тег предка вместе с сокращённым SHA-1 указанного commit-ish. Если указан параметр --first-parent, при обходе будут рассматриваться только первые родители каждого коммита.

Если при обходе найдено несколько тегов, будет выбран и выведен тег, для которого количество коммитов, отличающихся от указанного commit-ish, минимально. Здесь под количеством отличающихся коммитов понимается число коммитов, которые были бы показаны командой git log tag..input; оно должно быть минимально возможным.

Ошибки

Объекты дерева, а также объекты тегов, не указывающие на коммиты, описать нельзя. При описании blob-объектов игнорируются облегчённые теги, указывающие на blob-объекты, однако сам blob-объект всё равно описывается как <commit-ish>:<path>, хотя предпочтительнее было бы использовать облегчённый тег.

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