Русский ▾ Topics ▾ Latest version ▾ git-describe last updated in 2.42.0

НАЗВАНИЕ

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

ОБЗОР

git describe [--all] [--tags] [--contains] [--abbrev=<число>] [<указатель-коммита>…​]
git describe [--all] [--tags] [--contains] [--abbrev=<число>] --dirty[=<метка>]
git describe <blob-объект>

ОПИСАНИЕ

Команда находит самую последнюю метку, достижимую из коммита. Если метка указывает на коммит, то показывается только метка. В противном случае она добавляет к имени метки количество дополнительных коммитов поверх помеченного объекта и сокращённое имя объекта самого последнего коммита. Результатом является "читаемое человеком" имя объекта, которое также может использоваться для идентификации коммита для других команд git.

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

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

ПАРАМЕТРЫ

<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) сокращённого имени объекта использовать <число> цифр или столько цифр, сколько необходимо для формирования уникального имени объекта. Значение <число> = 0 подавляет длинный формат, показывая только ближайшую метку.

--candidates=<n>

Вместо рассмотрения только 10 самых последних меток в качестве кандидатов для описания входного указателя коммита рассматривать до <число> кандидатов. Увеличение <числа> сверх 10 займёт немного больше времени, но может дать более точный результат. Значение <число> = 0 приведёт к выводу только точных совпадений.

--exact-match

Выводить только точные совпадения (метка напрямую ссылается на указанный коммит). Это синоним для --candidates=0.

--debug

Подробно отображать информацию об используемой стратегии поиска в стандартный вывод ошибок. Имя метки по-прежнему будет выводиться в стандартный вывод.

--long

Всегда выводить длинный формат (метка, количество коммитов и сокращённое имя коммита), даже когда он совпадает с меткой. Это полезно, когда вы хотите видеть части имени объекта коммита в выводе "describe", даже если рассматриваемый коммит оказывается версией с меткой. Вместо простого вывода имени метки он опишет такой коммит как v1.2-0-gdeadbee (0-й коммит после метки v1.2, указывающей на объект deadbee…​.).

--match <шаблон>

Рассматривать только метки, соответствующие указанному шаблону glob(7), исключая префикс "refs/tags/". При использовании с --all также рассматривает локальные ветки и отслеживаемые внешние ссылки, соответствующие шаблону, исключая соответственно префиксы "refs/heads/" и "refs/remotes/"; ссылки других типов никогда не рассматриваются. Если указано несколько раз, будет накоплен список шаблонов, и будут рассматриваться метки, соответствующие любому из шаблонов. Используйте --no-match, чтобы очистить и сбросить список шаблонов.

--exclude <шаблон>

Не рассматривать метки, соответствующие указанному шаблону 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" может быть недостаточно для устранения неоднозначности этих коммитов.

СТРАТЕГИЯ ПОИСКА

Для каждого указанного указателя коммита git describe сначала будет искать метку, которая помечает точно этот коммит. Аннотированные метки всегда будут предпочтительнее легковесных меток, а метки с более новыми датами всегда будут предпочтительнее меток с более старыми датами. Если найдено точное совпадение, его имя будет выведено, и поиск остановится.

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

Если во время обхода найдено несколько меток, то будет выбрана и выведена метка, у которой наименьшее количество коммитов, отличных от входного указателя коммита. Здесь наименьшее количество отличий определяется как наименьшее возможное количество коммитов, которое показала бы команда git log метка..входной_объект.

ОШИБКИ

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

GIT

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