git-rev-parse

Название

git-rev-parse — выбор и обработка параметров

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

git rev-parse [<options>] <arg>…

Описание

Многие команды Git, похожие на порcelain-команды, принимают сочетание флагов (то есть параметров, начинающихся с тире -), параметров, предназначенных для базовой команды git rev-list, которую они используют внутри, а также флагов и параметров для других команд, вызываемых ниже по цепочке командой git rev-list. Основное назначение этой команды — дать вызывающим программам возможность различать их. Существует несколько других режимов работы, не имеющих отношения к описанному выше «разбору параметров командной строки».

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

Параметры

Режимы работы

Каждый из этих параметров должен стоять первым в командной строке.

--parseopt: Использовать git rev-parse в режиме разбора параметров (см. раздел PARSEOPT ниже). В этом режиме команду можно использовать вне репозитория или рабочего дерева, контролируемого репозиторием.
--sq-quote: Использовать git rev-parse в режиме экранирования для оболочки (см. раздел SQ-QUOTE ниже). В отличие от параметра --sq ниже, этот режим выполняет только экранирование. Ввод команды никак иначе не обрабатывается. В этом режиме команду можно использовать вне репозитория или рабочего дерева, контролируемого репозиторием.

Параметры для --parseopt

--keep-dashdash: Имеет смысл только в режиме --parseopt. Указывает анализатору параметров вывести первый встреченный --, а не пропускать его.
--stop-at-non-option: Имеет смысл только в режиме --parseopt. Позволяет анализатору параметров остановиться на первом аргументе, не являющемся параметром. Это можно использовать для разбора подкоманд, которые сами принимают параметры.
--stuck-long: Имеет смысл только в режиме --parseopt. Выводить параметры в длинной форме, если она доступна, и объединять их с аргументами.

Параметры фильтрации

--revs-only: Не выводить флаги и параметры, не предназначенные для команды git rev-list.
--no-revs: Не выводить флаги и параметры, предназначенные для команды git rev-list.
--flags: Не выводить параметры, не являющиеся флагами.
--no-flags: Не выводить параметры-флаги.

Параметры вывода

--default <arg>

Если пользователь не указал параметр, использовать вместо него <arg>.

--prefix <arg>

Вести себя так, как если бы git rev-parse была вызвана из подкаталога рабочего дерева <arg>. Все относительные имена файлов разрешаются так, как если бы к ним был добавлен префикс <arg>, и выводятся в таком виде.

Это можно использовать для преобразования аргументов команды, запущенной из подкаталога, чтобы их можно было использовать и после перехода в корневой каталог репозитория. Например:

prefix=$(git rev-parse --show-prefix)
cd "$(git rev-parse --show-toplevel)"
# rev-parse provides the -- needed for 'set'
eval "set $(git rev-parse --sq --prefix "$prefix" -- "$@")"

--verify

Проверить, что указан ровно один параметр и что его можно преобразовать в необработанное 20-байтовое значение SHA-1, пригодное для доступа к базе объектов. Если проверка пройдена, вывести его в стандартный вывод; в противном случае выдать ошибку.

Чтобы убедиться, что вывод действительно обозначает объект в вашей базе объектов и/или может использоваться как объект требуемого типа, можно добавить к параметру оператор снятия оболочки ^{type}. Например, git rev-parse "$VAR^{commit}" гарантирует, что $VAR обозначает существующий объект типа commit-ish (то есть коммит или аннотированный тег, указывающий на коммит). Чтобы убедиться, что $VAR обозначает существующий объект любого типа, можно использовать git rev-parse "$VAR^{object}".

Обратите внимание: если вы проверяете имя из ненадёжного источника, разумно использовать --end-of-options, чтобы аргумент с именем не был принят за другой параметр.

-q

--quiet

Имеет смысл только в режиме --verify. Не выводить сообщение об ошибке, если первый аргумент не является допустимым именем объекта; вместо этого молча завершить работу с ненулевым кодом. При успешном выполнении SHA-1 допустимых имён объектов выводятся в stdout.

--sq

Обычно для каждого флага и параметра выводится отдельная строка. Этот параметр выводит всё одной строкой, с корректным экранированием для передачи оболочке. Полезен, если ожидается, что параметр будет содержать пробелы и символы новой строки (например, при использовании pickaxe -S с git diff-*). В отличие от параметра --sq-quote, ввод команды по-прежнему интерпретируется обычным образом.

--short[=<length>]

То же, что --verify, но имя объекта сокращается до уникального префикса длиной не менее length символов. Минимальная длина — 4, значение по умолчанию определяется эффективным значением переменной конфигурации core.abbrev (см. git-config[1]).

--not

При выводе имён объектов добавлять перед ними префикс ^ и удалять префикс ^ у имён объектов, которые уже его содержат.

--abbrev-ref[=(strict|loose)]

Однозначное краткое имя объекта. Параметр core.warnAmbiguousRefs используется для выбора строгого режима сокращения.

--symbolic

Обычно имена объектов выводятся в форме SHA-1 (возможно, с префиксом ^); этот параметр выводит их в форме, максимально близкой к исходному вводу.

--symbolic-full-name

Похож на --symbolic, но не выводит ввод, который не является ссылкой (то есть имена ветвей или тегов; или, точнее, однозначно определяющую форму «heads/master», используемую, когда нужно указать ветвь «master» при наличии тега с неудачно совпадающим именем «master»), и отображает ссылки с полными именами (например, «refs/heads/master»).

--output-object-format=(sha1|sha256|storage)

Разрешить ввод oid в любом формате объектов, поддерживаемом текущим репозиторием.

При указании «sha1» преобразует при необходимости и возвращает oid sha1.

При указании «sha256» преобразует при необходимости и возвращает oid sha256.

При указании «storage» преобразует при необходимости и возвращает oid, закодированный с использованием алгоритма хеширования хранилища.

Параметры для объектов

--all

Показать все ссылки, найденные в refs/.

--branches[=<pattern>]

--tags[=<pattern>]

--remotes[=<pattern>]

Показать все ветви, теги или ветви отслеживания удалённых репозиториев соответственно (то есть ссылки, найденные соответственно в refs/heads, refs/tags или refs/remotes).

Если задан pattern, показываются только ссылки, соответствующие указанному шаблону glob оболочки. Если шаблон не содержит символов подстановки (?, * или [), он преобразуется в совпадение по префиксу добавлением /*.

--glob=<pattern>

Показать все ссылки, соответствующие шаблону glob оболочки pattern. Если шаблон не начинается с refs/, этот префикс добавляется автоматически. Если шаблон не содержит символов подстановки (?, * или [), он преобразуется в совпадение по префиксу добавлением /*.

--exclude=<glob-pattern>

Не включать ссылки, соответствующие <glob-pattern>, которые в противном случае были бы учтены следующими параметрами --all, --branches, --tags, --remotes или --glob. Повторные указания этого параметра накапливают шаблоны исключения вплоть до следующего параметра --all, --branches, --tags, --remotes или --glob (другие параметры и аргументы не сбрасывают накопленные шаблоны).

Шаблоны не должны начинаться с refs/heads, refs/tags или refs/remotes при применении соответственно к --branches, --tags или --remotes, а при применении к --glob или --all они должны начинаться с refs/. Если требуется конечный /*, его необходимо указать явно.

--exclude-hidden=(fetch|receive|uploadpack)

Не включать ссылки, которые были бы скрыты параметрами git-fetch, git-receive-pack или git-upload-pack, проверяя соответствующую конфигурацию fetch.hideRefs, receive.hideRefs или uploadpack.hideRefs вместе с transfer.hideRefs (см. git-config[1]). Этот параметр влияет на следующий параметр псевдоссылки --all или --glob и сбрасывается после их обработки.

--disambiguate=<prefix>

Показать каждый объект, имя которого начинается с указанного префикса. Чтобы случайно не вывести все объекты репозитория, длина <prefix> должна составлять не менее 4 шестнадцатеричных цифр.

Параметры для файлов

--local-env-vars

Вывести список переменных окружения GIT_*, относящихся к репозиторию (например, GIT_DIR или GIT_WORK_TREE, но не GIT_EDITOR). Выводятся только имена переменных, а не их значения, даже если они заданы.

--path-format=(absolute|relative)

Управляет поведением некоторых других параметров. Если задано значение absolute, пути, выводимые этими параметрами, будут абсолютными и каноническими. Если задано значение relative, пути будут относительными к текущему рабочему каталогу, если это возможно. Значение по умолчанию зависит от конкретного параметра.

Этот параметр можно указывать несколько раз; он влияет только на следующие за ним аргументы командной строки — до конца командной строки или до следующего указания этого параметра.

На следующие параметры влияет --path-format:

--git-dir

Показать $GIT_DIR, если задано. В противном случае показать путь к каталогу .git. Если путь относительный, он указывается относительно текущего рабочего каталога.

Если $GIT_DIR не задана и текущий каталог не распознан как находящийся внутри репозитория Git или рабочего дерева, вывести сообщение в stderr и завершить работу с ненулевым кодом.

--git-common-dir

Показать $GIT_COMMON_DIR, если задано, иначе $GIT_DIR.

--resolve-git-dir <path>

Проверить, является ли <path> допустимым репозиторием или git-файлом, указывающим на допустимый репозиторий, и вывести расположение репозитория. Если <path> — git-файл, выводится разрешённый путь к реальному репозиторию.

--git-path <path>

Разрешить путь "$GIT_DIR/<path>" с учётом других переменных перенаправления путей, таких как $GIT_OBJECT_DIRECTORY, $GIT_INDEX_FILE…. Например, если $GIT_OBJECT_DIRECTORY задана как /foo/bar, то "git rev-parse --git-path objects/abc" возвращает /foo/bar/abc.

--show-toplevel

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

--show-superproject-working-tree

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

--shared-index-path

Показать путь к общему файлу индекса в режиме разделённого индекса или пустую строку, если режим разделённого индекса не используется.

На следующие параметры не влияет --path-format:

--absolute-git-dir: Как --git-dir, но вывод всегда представляет собой канонизированный абсолютный путь.
--is-inside-git-dir: Если текущий рабочий каталог находится внутри каталога репозитория, вывести «true», в противном случае — «false».
--is-inside-work-tree: Если текущий рабочий каталог находится внутри рабочего дерева репозитория, вывести «true», в противном случае — «false».
--is-bare-repository: Если репозиторий является голым, вывести «true», в противном случае — «false».
--is-shallow-repository: Если репозиторий является неглубоким, вывести «true», в противном случае — «false».
--show-cdup: Если команда вызвана из подкаталога, показать путь от текущего каталога до корневого каталога (обычно это последовательность "../" или пустая строка).
--show-prefix: Если команда вызвана из подкаталога, показать путь от корневого каталога до текущего каталога.
--show-object-format[=(storage|input|output|compat)]: Показать формат объектов (алгоритм хеширования), используемый репозиторием для хранения внутри каталога .git, ввода, вывода или совместимости. Для ввода можно вывести несколько алгоритмов, разделённых пробелами. Если запрошен compat, а алгоритм совместимости не включён, выводится пустая строка. Если параметр не указан, используется значение «storage».
--show-ref-format: Показать формат хранения ссылок, используемый репозиторием.

Другие параметры

--since=<datestring>
--after=<datestring>: Разобрать строку даты и вывести соответствующий параметр --max-age= для git rev-list.
--until=<datestring>
--before=<datestring>: Разобрать строку даты и вывести соответствующий параметр --min-age= для git rev-list.
<arg>…: Флаги и параметры для разбора.

Указание ревизий

Параметр ревизии <rev> обычно, но не обязательно, задаёт объект коммита. Для него используется так называемый синтаксис extended SHA-1. Ниже приведены различные способы записи имён объектов. Имена, перечисленные ближе к концу этого списка, обозначают деревья и blob-объекты, содержащиеся в коммите.

Примечание

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

<sha1>, например dae86e1950b1277e545cee180551750029cfe735, dae86e

Полное имя объекта SHA-1 (40-байтовая шестнадцатеричная строка) или начальная подстрока, уникальная в пределах репозитория. Например, dae86e1950b1277e545cee180551750029cfe735 и dae86e обозначают один и тот же объект коммита, если в вашем репозитории нет другого объекта, имя которого начинается с dae86e.

<describeOutput>, например v1.7.4.2-679-g3bee7fb

Результат команды git describe; то есть ближайший тег, за которым может следовать дефис и число коммитов, затем дефис, g и сокращённое имя объекта.

<refname>, например master, heads/master, refs/heads/master

Символическое имя ссылки. Например, master обычно означает объект коммита, на который указывает refs/heads/master. Если у вас есть и heads/master, и tags/master, можно явно указать heads/master, чтобы сообщить Git, какой из них имеется в виду. Если имя неоднозначно, <refname> разрешается по первому совпадению в соответствии со следующими правилами:

Если существует $GIT_DIR/<refname>, имеется в виду именно оно (обычно это полезно только для HEAD, FETCH_HEAD, ORIG_HEAD, MERGE_HEAD, REBASE_HEAD, REVERT_HEAD, CHERRY_PICK_HEAD, BISECT_HEAD и AUTO_MERGE);
иначе, если существует refs/<refname>;
иначе, если существует refs/tags/<refname>;
иначе, если существует refs/heads/<refname>;
иначе, если существует refs/remotes/<refname>;
иначе, если существует refs/remotes/<refname>/HEAD.

HEAD

обозначает коммит, на основе которого вы внесли изменения в рабочее дерево.

FETCH_HEAD

содержит сведения о ветке, из которой вы извлекли данные из удалённого репозитория при последнем вызове git fetch.

ORIG_HEAD

создаётся командами, которые существенно перемещают ваш HEAD (git am, git merge, git rebase, git reset), чтобы сохранить положение HEAD перед выполнением команды и упростить возврат вершины ветки к состоянию, в котором она находилась до запуска этих команд.

MERGE_HEAD

содержит сведения о коммите (коммитах), который вы сливаете в свою ветку при запуске git merge.

REBASE_HEAD

во время перебазирования содержит сведения о коммите, на котором операция приостановлена в данный момент — из-за конфликтов или команды edit при интерактивном перебазировании.

REVERT_HEAD

содержит сведения о коммите, отменяемом при запуске git revert.

CHERRY_PICK_HEAD

содержит сведения о коммите, выбираемом при запуске git cherry-pick.

BISECT_HEAD

содержит сведения о текущем коммите, который нужно проверить при запуске git bisect --no-checkout.

AUTO_MERGE

содержит сведения об объекте дерева, соответствующем состоянию, которое стратегия слияния ort записала в рабочее дерево, когда при слиянии возникли конфликты.

Обратите внимание: любой из перечисленных выше случаев refs/* может относиться как к каталогу $GIT_DIR/refs, так и к файлу $GIT_DIR/packed-refs. Формат кодирования имён ссылок не определён, однако предпочтительно использовать UTF-8, поскольку при обработке некоторых выходных данных может предполагаться, что имена ссылок закодированы в UTF-8.

@

@ без дополнительных символов — это сокращённая запись для HEAD.

[<refname>]@{<date>}, например master@{yesterday}, HEAD@{5 minutes ago}

Ссылка с суффиксом @, за которым в фигурных скобках указана дата (например, {yesterday}, {1 month 2 weeks 3 days 1 hour 1 second ago} или {1979-02-26 18:30:00}), задаёт значение ссылки в более ранний момент времени. Этот суффикс можно использовать только непосредственно после имени ссылки, и у ссылки должен существовать журнал ($GIT_DIR/logs/<ref>). Обратите внимание: таким образом определяется состояние вашей локальной ссылки в указанный момент времени; например, состояние вашей локальной ветки master на прошлой неделе. Если нужно просмотреть коммиты, созданные в определённый период, см. --since и --until.

<refname>@{<n>}, например master@{1}

Ссылка с суффиксом @, за которым в фигурных скобках указано порядковое число (например, {1}, {15}), задаёт n-е предыдущее значение этой ссылки. Например, master@{1} — это непосредственно предыдущее значение master, а master@{5} — пятое предыдущее значение master. Этот суффикс можно использовать только непосредственно после имени ссылки, и у ссылки должен существовать журнал ($GIT_DIR/logs/<refname>).

@{<n>}, например @{1}

Конструкцию @ можно использовать с пустой частью ссылки, чтобы получить запись журнала ссылок текущей ветки. Например, если вы находитесь в ветке blabla, то @{1} означает то же, что и blabla@{1}.

@{-<n>}, например @{-1}

Конструкция @{-<n>} обозначает ветку или коммит, на который переключились в n-й раз до текущего переключения.

[<branchname>]@{upstream}, например master@{upstream}, @{u}

Ветку B можно настроить так, чтобы она основывалась на ветке X (настраивается с помощью branch.<name>.merge) в удалённом репозитории R (настраивается с помощью branch.<name>.remote). B@{u} обозначает ветку удалённого отслеживания для ветки X, полученной из удалённого репозитория R; обычно она находится в refs/remotes/R/X.

[<branchname>]@{push}, например master@{push}, @{push}

Суффикс @{push} указывает ветку, «куда мы отправили бы изменения», если бы команда git push была выполнена при выбранной ветке branchname (или текущей HEAD, если имя ветки не указано). Как и для @{upstream}, указывается ветка удалённого отслеживания, соответствующая этой ветке в удалённом репозитории.

Вот пример, который поможет разобраться:

$ git config push.default current
$ git config remote.pushdefault myfork
$ git switch -c mybranch origin/master

$ git rev-parse --symbolic-full-name @{upstream}
refs/remotes/origin/master

$ git rev-parse --symbolic-full-name @{push}
refs/remotes/myfork/mybranch

Обратите внимание, что в примере настроен треугольный процесс работы: изменения извлекаются из одного места, а отправляются в другое. В процессе работы без такой схемы @{push} совпадает с @{upstream}, поэтому в нём нет необходимости.

Этот суффикс также допускается записывать прописными буквами; регистр не влияет на его значение.

<rev>^[<n>], например HEAD^, v1.5.1^0

Суффикс ^ у параметра ревизии обозначает первого родителя этого объекта коммита. ^<n> обозначает n-го родителя (то есть <rev>^ эквивалентно <rev>^1). Особое правило: <rev>^0 обозначает сам коммит и используется, когда <rev> — это имя объекта тега, указывающего на объект коммита.

<rev>~[<n>], например HEAD~, master~3

Суффикс ~ у параметра ревизии обозначает первого родителя этого объекта коммита. Суффикс ~<n> у параметра ревизии обозначает предка указанного объекта коммита, находящегося на n поколений раньше, если идти только по первым родителям. То есть <rev>~3 эквивалентно <rev>^^^, а оно, в свою очередь, эквивалентно <rev>^1^1^1. Ниже приведена иллюстрация использования этой формы.

<rev>^{<type>}, например v0.99.8^{commit}

Суффикс ^, за которым в фигурных скобках указано имя типа объекта, означает, что объект по адресу <rev> нужно разыменовывать рекурсивно, пока не будет найден объект типа <type> или пока разыменование объекта не станет невозможным (в этом случае возникнет ошибка). Например, если <rev> — это объект типа commit-ish, то <rev>^{commit} обозначает соответствующий объект коммита. Аналогично, если <rev> — это объект типа tree-ish, то <rev>^{tree} обозначает соответствующий объект дерева. <rev>^0 — это сокращённая запись для <rev>^{commit}.

<rev>^{object} можно использовать, чтобы убедиться, что <rev> обозначает существующий объект, не требуя, чтобы <rev> был тегом, и не разыменовывая <rev>; поскольку тег уже является объектом, для получения объекта его не нужно разыменовывать ни разу.

<rev>^{tag} можно использовать, чтобы убедиться, что <rev> обозначает существующий объект-тег.

<rev>^{}, например v0.99.8^{}

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

<rev>^{/<text>}, например HEAD^{/fix nasty bug}

Суффикс ^ у параметра ревизии, за которым следует пара фигурных скобок с текстом, начинающимся с косой черты, эквивалентен синтаксису :/fix nasty bug, описанному ниже, но возвращает самый поздний подходящий коммит, достижимый из <rev> до ^.

:/<text>, например :/fix nasty bug

Двоеточие, за которым следуют косая черта и текст, обозначает коммит, сообщение которого соответствует указанному регулярному выражению. Это имя возвращает самый поздний подходящий коммит, достижимый из любой ссылки, включая HEAD. Регулярное выражение может соответствовать любой части сообщения коммита. Чтобы найти сообщения, начинающиеся с заданной строки, можно использовать, например, :/^foo. Специальная последовательность :/! зарезервирована для модификаторов сопоставления. :/!-foo задаёт отрицательное совпадение, а :/!!foo соответствует буквальному символу !, за которым следует foo. Любая другая последовательность, начинающаяся с :/!, пока зарезервирована. В зависимости от указанного текста правила разбиения слов оболочкой могут потребовать дополнительного экранирования.

<rev>:<path>, например HEAD:README, master:./README

Суффикс :, за которым следует путь, обозначает blob-объект или дерево по указанному пути в объекте типа tree-ish, заданном частью перед двоеточием. Путь, начинающийся с ./ или ../, отсчитывается от текущего рабочего каталога. Указанный путь будет преобразован в путь относительно корневого каталога рабочего дерева. Это особенно полезно для обращения к blob-объекту или дереву из коммита либо дерева с той же структурой, что и у рабочего дерева.

:[<n>:]<path>, например :0:README, :README

Двоеточие, за которым может следовать номер стадии (от 0 до 3) и ещё одно двоеточие, а затем путь, обозначает blob-объект в индексе по указанному пути. Если номер стадии (и следующее за ним двоеточие) не указан, подразумевается запись стадии 0. При слиянии стадия 1 соответствует общему предку, стадия 2 — версии целевой ветки (обычно текущей ветки), а стадия 3 — версии ветки, которая сливается.

Ниже приведена иллюстрация Джона Лёлигера. Узлы коммитов B и C являются родителями узла коммита A. Родительские коммиты упорядочены слева направо.

G   H   I   J
 \ /     \ /
  D   E   F
   \  |  / \
    \ | /   |
     \|/    |
      B     C
       \   /
        \ /
         A

A =      = A^0
B = A^   = A^1     = A~1
C =      = A^2
D = A^^  = A^1^1   = A~2
E = B^2  = A^^2
F = B^3  = A^^3
G = A^^^ = A^1^1^1 = A~3
H = D^2  = B^^2    = A^^^2  = A~2^2
I = F^   = B^3^    = A^^3^
J = F^2  = B^3^2   = A^^3^2

Указание диапазонов

Команды обхода истории, такие как git log, работают с набором коммитов, а не только с одним коммитом.

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

Указание нескольких ревизий означает набор коммитов, достижимых из любого из указанных коммитов.

Набор коммитов, достижимых из коммита, включает сам коммит и коммиты в его цепочке предков.

Чтобы указать набор связанных коммитов (называемый «диапазоном ревизий»), можно использовать несколько вариантов синтаксиса, показанных ниже.

Исключение коммитов

Запись ^<rev> (с каретой): Чтобы исключить коммиты, достижимые из коммита, используется запись с префиксом ^. Например, ^r1 r2 означает коммиты, достижимые из r2, за исключением коммитов, достижимых из r1 (то есть r1 и его предков).

Записи диапазонов с точками

Запись диапазона .. (две точки): Операция над множествами ^r1 r2 встречается так часто, что для неё предусмотрена сокращённая запись. Если есть два коммита, r1 и r2 (названные в соответствии с синтаксисом, описанным выше в разделе «Указание ревизий»), можно запросить коммиты, достижимые из r2, исключив коммиты, достижимые из r1, с помощью ^r1 r2; эта запись сокращается до r1..r2.
Запись симметрической разности ... (три точки): Похожая запись r1...r2 называется симметрической разностью r1 и r2 и определяется как r1 r2 --not $(git merge-base --all r1 r2). Это набор коммитов, достижимых из r1 (левая сторона) или r2 (правая сторона), но не из обоих одновременно.

В этих двух сокращённых записях можно опустить один конец диапазона; по умолчанию вместо него будет использован HEAD. Например, origin.. — это сокращение для origin..HEAD, которое отвечает на вопрос: «Что я сделал с тех пор, как отделился от исходной ветки?» Аналогично, ..origin — это сокращение для HEAD..origin, которое отвечает на вопрос: «Что сделали в исходной ветке с тех пор, как я от неё отделился?» Обратите внимание: .. означает HEAD..HEAD — пустой диапазон, который одновременно достижим и недостижим из HEAD.

Существуют команды, специально предназначенные для работы с двумя различными диапазонами (например, «git range-diff R1 R2» для сравнения двух диапазонов), но это исключение. Если не указано иное, все команды «git», работающие с набором коммитов, обрабатывают один диапазон ревизий. Иными словами, запись двух диапазонов с двумя точками подряд, например:

$ git log A..B C..D

для большинства команд не задаёт два диапазона ревизий. Вместо этого она обозначает один связный набор коммитов: коммиты, достижимые из B или D, но не достижимые ни из A, ни из C. В линейной истории, такой как эта:

---A---B---o---o---C---D

поскольку A и B достижимы из C, диапазон ревизий, задаваемый этими двумя диапазонами с точками, состоит только из одного коммита D.

Другие сокращённые записи родителей <rev>^

Существуют ещё три сокращённые записи, особенно полезные для коммитов слияния; они задают набор, образованный коммитом и его родительскими коммитами.

Запись r1^@ означает всех родителей r1.

Запись r1^! включает коммит r1, но исключает всех его родителей. Сама по себе эта запись обозначает только коммит r1.

Запись <rev>^-[<n>] включает <rev>, но исключает n-го родителя (то есть является сокращением для <rev>^<n>..<rev>); если <n> не указано, используется значение 1. Обычно это полезно для коммитов слияния: достаточно передать <commit>^-, чтобы получить все коммиты ветки, слитой в коммите слияния <commit> (включая сам <commit>).

Если <rev>^<n> использовалась для указания одного родительского коммита, то эти три записи также учитывают его родителей. Например, можно указать HEAD^2^@, но нельзя указать HEAD^@^2.

Краткое описание диапазонов ревизий

<rev>: Включить коммиты, достижимые из <rev> (то есть <rev> и его предков).
^<rev>: Исключить коммиты, достижимые из <rev> (то есть <rev> и его предков).
<rev1>..<rev2>: Включить коммиты, достижимые из <rev2>, но исключить те, которые достижимы из <rev1>. Если <rev1> или <rev2> не указана, вместо неё используется HEAD.
<rev1>...<rev2>: Включить коммиты, достижимые из <rev1> или <rev2>, но исключить те, которые достижимы из обоих. Если <rev1> или <rev2> не указана, вместо неё используется HEAD.
<rev>^@, например HEAD^@: Суффикс ^ с символом @ эквивалентен перечислению всех родителей <rev> (то есть включает всё, что достижимо из его родителей, но не сам коммит).
<rev>^!, например HEAD^!: Суффикс ^ с восклицательным знаком эквивалентен указанию коммита <rev> и всех его родителей с префиксом ^, чтобы исключить их (и их предков).
<rev>^-<n>, например HEAD^-, HEAD^-2: Эквивалентно <rev>^<n>..<rev>; если <n> не указано, используется значение 1.

Ниже приведены несколько примеров, использующих иллюстрацию Лёлигера выше; для каждого примера подробно показано раскрытие записи и выбор коммитов на каждом шаге:

   Args   Expanded arguments    Selected commits
   D                            G H D
   D F                          G H I J D F
   ^G D                         H D
   ^D B                         E I J F B
   ^D B C                       E I J F B C
   C                            I J F C
   B..C   = ^B C                C
   B...C  = B ^F C              G H D E B C
   B^-    = B^..B
          = ^B^1 B              E I J F B
   C^@    = C^1
          = F                   I J F
   B^@    = B^1 B^2 B^3
          = D E F               D G H E F I J
   C^!    = C ^C^@
          = C ^C^1
          = C ^F                C
   B^!    = B ^B^@
          = B ^B^1 ^B^2 ^B^3
          = B ^D ^E ^F          B
   F^! D  = F ^I ^J D           G H D F

Parseopt

В режиме --parseopt команда git rev-parse помогает преобразовывать параметры, предоставляя shell-скриптам те же возможности, что и встроенным командам C. Она нормализует параметры (например, разбивает объединённые значения отдельных параметров) подобно тому, как это делает getopt(1).

Она считывает из стандартного ввода спецификацию параметров, которые нужно разобрать и распознать, а в стандартный вывод записывает строку, подходящую для sh(1) eval, чтобы заменить аргументы нормализованными. В случае ошибки команда выводит справку по использованию в поток стандартного вывода ошибок и завершается с кодом 129.

Примечание: при передаче результата в eval не забудьте взять его в кавычки. См. пример ниже.

Формат входных данных

Формат входных данных git rev-parse --parseopt полностью текстовый. Он состоит из двух частей, разделённых строкой, содержащей только --. Строки до разделителя (их должна быть одна или несколько) используются для справки по использованию. Строки после разделителя описывают параметры.

Каждая строка с параметрами имеет следующий формат:

<opt-spec><flags>*<arg-hint>? SP+ help LF

<opt-spec>

Формат: символ короткого параметра, затем через запятую — имя длинного параметра. Можно указать только одну из этих частей, но хотя бы одна обязательна. В них не должно быть символов из <flags>. h,help, dry-run и f — примеры корректного <opt-spec>.

<flags>

<flags> может принимать значения *, =, ? или !.

Используйте =, если параметр принимает аргумент.
Используйте ?, если параметр принимает необязательный аргумент. Вероятно, вам понадобится режим --stuck-long, чтобы однозначно разобрать необязательный аргумент.
Используйте *, если этот параметр не должен отображаться в справке по использованию, сформированной для аргумента -h. Он отображается для --help-all, как описано в gitcli[7].
Используйте !, чтобы не предоставлять соответствующий длинный параметр с отрицанием.

<arg-hint>

<arg-hint>, если указан, используется в справке как имя аргумента для параметров, принимающих аргументы. <arg-hint> заканчивается на первом пробеле. В качестве разделителя слов в подсказке из нескольких слов обычно используют дефис.

Оставшаяся часть строки после удаления пробелов используется как справочный текст для параметра.

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

Пример

OPTS_SPEC="\
some-command [<options>] <args>...

some-command does foo and bar!
--
h,help!   show the help

foo       some nifty option --foo
bar=      some cool option --bar with an argument
baz=arg   another cool option --baz with a named argument
qux?path  qux may take a path argument but has meaning by itself

  An option group Header
C?        option C with an optional argument"

eval "$(echo "$OPTS_SPEC" | git rev-parse --parseopt -- "$@" || echo exit $?)"

Текст справки по использованию

Если в приведённом выше примере для "$@" задано значение -h или --help, будет показан следующий текст справки по использованию:

usage: some-command [<options>] <args>...

    some-command does foo and bar!

    -h, --help            show the help
    --[no-]foo            some nifty option --foo
    --[no-]bar ...        some cool option --bar with an argument
    --[no-]baz <arg>      another cool option --baz with a named argument
    --[no-]qux[=<path>]   qux may take a path argument but has meaning by itself

An option group Header
    -C[...]               option C with an optional argument

Sq-quote

В режиме --sq-quote команда git rev-parse выводит в стандартный поток вывода одну строку, подходящую для sh(1) eval. Эта строка формируется путём нормализации аргументов, следующих за --sq-quote. Выполняется только заключение аргументов в кавычки.

Если вы хотите, чтобы входные команды по-прежнему обрабатывались git rev-parse обычным образом до заключения результата в кавычки для оболочки, см. параметр --sq.

Пример

$ cat >your-git-script.sh <<\EOF
#!/bin/sh
args=$(git rev-parse --sq-quote "$@")   # quote user-supplied arguments
command="git frotz -n24 $args"          # and use it inside a handcrafted
                                        # command line
eval "$command"
EOF

$ sh your-git-script.sh "a b'c"

Примеры

Вывести имя объекта текущего коммита:
```
$ git rev-parse --verify HEAD
```
Вывести имя объекта коммита, указанного в ревизии из переменной оболочки $REV:
```
$ git rev-parse --verify --end-of-options $REV^{commit}
```
Вызовет ошибку, если $REV пуста или содержит недопустимую ревизию.
Аналогично предыдущему примеру:
```
$ git rev-parse --default master --verify --end-of-options $REV
```
но если $REV пуста, будет выведено имя объекта коммита из master.

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