githooks

applypatch-msg

Этот хук вызывается командой git-am[1]. Он принимает один параметр — имя файла, содержащего предполагаемое сообщение журнала коммита. Завершение с ненулевым кодом возврата приводит к тому, что git am прерывает выполнение до применения патча.

Хук может редактировать файл сообщения на месте и использоваться для приведения сообщения к стандартному формату проекта. Его также можно использовать, чтобы отклонить коммит после проверки файла сообщения.

Хук applypatch-msg по умолчанию, если он включён, запускает хук commit-msg, если последний включён.

pre-applypatch

Этот хук вызывается командой git-am[1]. Он не принимает параметров и вызывается после применения патча, но до создания коммита.

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

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

Хук pre-applypatch по умолчанию, если он включён, запускает хук pre-commit, если последний включён.

post-applypatch

Этот хук вызывается командой git-am[1]. Он не принимает параметров и вызывается после применения патча и создания коммита.

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

pre-commit

Этот хук вызывается командой git-commit[1]; его можно обойти с помощью параметра --no-verify. Он не принимает параметров и вызывается до получения предполагаемого сообщения журнала коммита и создания коммита. Завершение этого скрипта с ненулевым кодом возврата приводит к тому, что команда git commit прерывает выполнение до создания коммита.

Все хуки git commit вызываются с переменной окружения GIT_EDITOR=:, если команда не будет запускать редактор для изменения сообщения коммита.

Хук pre-commit по умолчанию, если он включён, запрещает добавление имён файлов с символами, не входящими в ASCII, и строк с пробелами в конце. Проверку символов, не входящих в ASCII, можно отключить, задав для параметра конфигурации hooks.allownonascii значение true.

pre-merge-commit

Этот хук вызывается командой git-merge[1]; его можно обойти с помощью параметра --no-verify. Он не принимает параметров и вызывается после успешного слияния, но до получения предполагаемого сообщения журнала коммита для создания коммита. Завершение этого скрипта с ненулевым кодом возврата приводит к тому, что команда git merge прерывает выполнение до создания коммита.

Хук pre-merge-commit по умолчанию, если он включён, запускает хук pre-commit, если последний включён.

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

Если слияние не удаётся выполнить автоматически, необходимо разрешить конфликты и зафиксировать результат отдельно (см. git-merge[1]). В этом случае данный хук не запускается, но запускается хук pre-commit, если он включён.

prepare-commit-msg

Этот хук вызывается командой git-commit[1] сразу после подготовки сообщения журнала по умолчанию и до запуска редактора.

Он принимает от одного до трёх параметров. Первый — имя файла, содержащего сообщение журнала коммита. Второй — источник сообщения коммита; им может быть: message (если указан параметр -m или -F); template (если указан параметр -t или задан параметр конфигурации commit.template); merge (если коммит является коммитом слияния или существует файл .git/MERGE_MSG); squash (если существует файл .git/SQUASH_MSG); или commit с последующим именем объекта-коммита (если указан параметр -c, -C или --amend).

Если код возврата ненулевой, git commit прервёт выполнение.

Назначение этого хука — редактировать файл сообщения на месте; параметр --no-verify не отключает его. Ненулевой код возврата означает сбой хука и прерывает создание коммита. Его не следует использовать вместо хука pre-commit.

Пример хука prepare-commit-msg, поставляемый с Git, удаляет справочное сообщение из закомментированной части шаблона коммита.

commit-msg

Этот хук вызывается командами git-commit[1] и git-merge[1]; его можно обойти с помощью параметра --no-verify. Он принимает один параметр — имя файла, содержащего предполагаемое сообщение журнала коммита. Завершение с ненулевым кодом возврата приводит к прерыванию команды.

Хук может редактировать файл сообщения на месте и использоваться для приведения сообщения к стандартному формату проекта. Его также можно использовать, чтобы отклонить коммит после проверки файла сообщения.

Хук commit-msg по умолчанию, если он включён, обнаруживает повторяющиеся завершающие строки Signed-off-by и прерывает создание коммита, если находит такую строку.

post-commit

Этот хук вызывается командой git-commit[1]. Он не принимает параметров и вызывается после создания коммита.

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

pre-rebase

Этот хук вызывается командой git-rebase[1] и может использоваться для предотвращения перебазирования ветки. Хук может вызываться с одним или двумя параметрами. Первый параметр — вышестоящая ветка, от которой была ответвлена серия коммитов. Второй параметр — перебазируемая ветка; он не задаётся при перебазировании текущей ветки.

post-checkout

Этот хук вызывается после обновления рабочего дерева при запуске git-checkout[1] или git-switch[1]. Хук получает три параметра: ссылку на предыдущий HEAD, ссылку на новый HEAD (которая могла измениться или остаться прежней) и флаг, указывающий, было ли переключение переключением ветки (смена ветки, flag=1) или переключением файла (извлечение файла из индекса, flag=0). Этот хук не может повлиять на результат выполнения git switch или git checkout, за исключением того, что код возврата хука становится кодом возврата этих двух команд.

Он также запускается после git-clone[1], если не используется параметр --no-checkout (-n). Первый параметр, передаваемый хуку, — нулевая ссылка, второй — ссылка на новый HEAD, а флаг всегда равен 1. То же относится к git worktree add, если не используется --no-checkout.

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

post-merge

Этот хук вызывается командой git-merge[1] при выполнении git pull в локальном репозитории. Хук принимает один параметр — флаг состояния, указывающий, было ли выполненное слияние с подавлением истории (squash). Этот хук не может повлиять на результат выполнения git merge и не запускается, если слияние завершилось неудачей из-за конфликтов.

Этот хук можно использовать совместно с соответствующим хуком pre-commit для сохранения и восстановления любых метаданных рабочего дерева (например, разрешений/владельца, списков контроля доступа и т. д.). Пример реализации приведён в contrib/hooks/setgitperms.perl.

pre-push

Этот хук вызывается командой git-push[1] и может использоваться для предотвращения отправки изменений. Хук вызывается с двумя параметрами, содержащими имя и расположение целевого удалённого репозитория; если именованный удалённый репозиторий не используется, оба значения будут одинаковыми.

Информация о том, что будет отправлено, передаётся хуку через стандартный ввод строками следующего формата:

<local-ref> SP <local-object-name> SP <remote-ref> SP <remote-object-name> LF

Например, если выполнить команду git push origin master:foreign, хук получит строку следующего вида:

refs/heads/master 67890 refs/heads/foreign 12345

однако полное имя объекта будет передано целиком. Если внешняя ссылка ещё не существует, значением <remote-object-name> будет имя объекта, состоящее из одних нулей. Если ссылку нужно удалить, значение <local-ref> будет передано как (delete), а значением <local-object-name> будет имя объекта, состоящее из одних нулей. Если локальный коммит был указан не именем, которое можно развернуть (например, HEAD~ или именем объекта), он будет передан в исходном виде.

Если этот хук завершается с ненулевым кодом возврата, git push прервёт выполнение, не отправив никаких изменений. Информацию о причине отклонения отправки можно передать пользователю, записав её в стандартный поток ошибок.

pre-receive

Этот хук вызывается командой git-receive-pack[1] при обработке git push и обновлении ссылок в репозитории. Хук pre-receive вызывается непосредственно перед началом обновления ссылок в удалённом репозитории. Его код возврата определяет, завершится ли обновление успешно.

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

<old-oid> SP <new-oid> SP <ref-name> LF

где <old-oid> — старое имя объекта, сохранённое в ссылке, <new-oid> — новое имя объекта, которое будет сохранено в ссылке, а <ref-name> — полное имя ссылки. При создании новой ссылки <old-oid> — это имя объекта, состоящее из одних нулей.

Если хук завершается с ненулевым кодом возврата, ни одна ссылка не будет обновлена. Если хук завершается с нулевым кодом возврата, обновление отдельных ссылок всё ещё может быть запрещено хуком update.

Стандартный вывод и стандартный поток ошибок перенаправляются на git send-pack на другой стороне, поэтому сообщения для пользователя можно просто вывести с помощью echo.

Количество параметров отправки, заданных в командной строке git push --push-option=..., можно получить из переменной окружения GIT_PUSH_OPTION_COUNT, а сами параметры находятся в GIT_PUSH_OPTION_0, GIT_PUSH_OPTION_1,…​ Если согласовано не использовать этап передачи параметров отправки, переменные окружения не будут заданы. Если клиент выбирает передачу параметров отправки, но не передаёт ни одного, счётчик будет равен нулю, GIT_PUSH_OPTION_COUNT=0.

Некоторые особенности описаны в разделе «Среда карантина» документации git-receive-pack[1].

update

Этот хук вызывается командой git-receive-pack[1] при обработке git push и обновлении ссылок в репозитории. Хук update вызывается непосредственно перед обновлением ссылки в удалённом репозитории. Его код возврата определяет, завершится ли обновление ссылки успешно.

Хук выполняется отдельно для каждой обновляемой ссылки и принимает три параметра:

Нулевой код возврата хука update разрешает обновление ссылки. Завершение с ненулевым кодом возврата запрещает команде git receive-pack обновлять эту ссылку.

Этот хук можно использовать, чтобы предотвратить обновление forced для определённых ссылок, проверяя, что имя объекта соответствует объекту-коммиту, являющемуся потомком объекта-коммита, указанного старым именем объекта. Иными словами, чтобы обеспечить политику «только перемотка вперёд».

Его также можно использовать для записи состояния old..new в журнал. Однако хук не знает полного набора веток, поэтому при наивном использовании он будет отправлять отдельное электронное письмо для каждой ссылки. Для этой задачи лучше подходит хук post-receive.

В среде, где доступ пользователей ограничен выполнением команд Git через сеть, этот хук можно использовать для реализации контроля доступа без опоры на владение файлами и членство в группах. О том, как ограничить доступ пользователя только командами Git с помощью командной оболочки входа, см. git-shell[1].

Стандартный вывод и стандартный поток ошибок перенаправляются на git send-pack на другой стороне, поэтому сообщения для пользователя можно просто вывести с помощью echo.

Хук update по умолчанию, если он включён, и если параметр конфигурации hooks.allowunannotated не задан или имеет значение false, запрещает отправку тегов без аннотаций.

proc-receive

Этот хук вызывается командой git-receive-pack[1]. Если на сервере задана многозначная переменная конфигурации receive.procReceiveRefs и имена ссылок в командах, отправленных в receive-pack, соответствуют ей, эти команды будут обработаны данным хуком вместо внутренней функции execute_commands(). Этот хук отвечает за обновление соответствующих ссылок и передачу результатов обратно в receive-pack.

Этот хук выполняется один раз для операции приёма. Он не принимает аргументов, но использует протокол в формате pkt-line для обмена данными с receive-pack: чтения команд и параметров отправки, а также передачи результатов. В следующем примере протокола буква S обозначает receive-pack, а буква H — этот хук.

# Version and features negotiation.
S: PKT-LINE(version=1\0push-options atomic...)
S: flush-pkt
H: PKT-LINE(version=1\0push-options...)
H: flush-pkt

# Send commands from server to the hook.
S: PKT-LINE(<old-oid> <new-oid> <ref>)
S: ... ...
S: flush-pkt
# Send push-options only if the 'push-options' feature is enabled.
S: PKT-LINE(push-option)
S: ... ...
S: flush-pkt

# Receive results from the hook.
# OK, run this command successfully.
H: PKT-LINE(ok <ref>)
# NO, I reject it.
H: PKT-LINE(ng <ref> <reason>)
# Fall through, let 'receive-pack' execute it.
H: PKT-LINE(ok <ref>)
H: PKT-LINE(option fall-through)
# OK, but has an alternate reference.  The alternate reference name
# and other status can be given in option directives.
H: PKT-LINE(ok <ref>)
H: PKT-LINE(option refname <refname>)
H: PKT-LINE(option old-oid <old-oid>)
H: PKT-LINE(option new-oid <new-oid>)
H: PKT-LINE(option forced-update)
H: ... ...
H: flush-pkt

Каждая команда для хука proc-receive может указывать на псевдоссылку и всегда имеет нулевой old-oid, тогда как хук proc-receive может обновить альтернативную ссылку, которая уже может существовать с ненулевым old-oid. В этом случае хук использует директивы «option», чтобы сообщить расширенные атрибуты ссылки, указанной предшествующей директивой «ok».

Команды в отчёте этого хука должны располагаться в том же порядке, что и во входных данных. Код возврата хука proc-receive определяет только успех или неудачу группы переданных ему команд, за исключением случаев использования атомарной отправки.

post-receive

Этот хук вызывается командой git-receive-pack[1] при обработке git push и обновлении ссылок в репозитории. Хук выполняется в удалённом репозитории один раз после обработки всех предполагаемых обновлений ссылок, если в результате обновлена хотя бы одна ссылка.

Хук не принимает аргументов. Для каждой успешно обновлённой ссылки он получает через стандартный ввод одну строку в том же формате, что и хук pre-receive.

Этот хук не влияет на результат выполнения git receive-pack, поскольку вызывается после завершения основной работы.

Этот хук заменяет хук post-update, поскольку получает не только имена всех ссылок, но и их старые и новые значения.

Стандартный вывод и стандартный поток ошибок перенаправляются на git send-pack на другой стороне, поэтому сообщения для пользователя можно просто вывести с помощью echo.

Хук post-receive по умолчанию пуст, но в каталоге contrib/hooks дистрибутива Git имеется пример скрипта post-receive-email, реализующий отправку писем о коммитах.

Количество параметров отправки, заданных в командной строке git push --push-option=..., можно получить из переменной окружения GIT_PUSH_OPTION_COUNT, а сами параметры находятся в GIT_PUSH_OPTION_0, GIT_PUSH_OPTION_1,…​ Если согласовано не использовать этап передачи параметров отправки, переменные окружения не будут заданы. Если клиент выбирает передачу параметров отправки, но не передаёт ни одного, счётчик будет равен нулю, GIT_PUSH_OPTION_COUNT=0.

Дополнительные сведения см. в разделе «post-receive» документации git-receive-pack[1].

post-update

Этот хук вызывается командой git-receive-pack[1] при обработке git push и обновлении ссылок в репозитории. Он выполняется в удалённом репозитории один раз после обновления всех ссылок.

Хук принимает переменное число параметров, каждый из которых является именем фактически обновлённой ссылки.

Этот хук предназначен главным образом для уведомления и не может повлиять на результат выполнения git receive-pack.

Хук post-update позволяет определить, какие вершины веток были отправлены, но не сообщает их исходные и обновлённые значения, поэтому для записи изменений old..new он подходит плохо. Хук post-receive получает как исходные, так и обновлённые значения ссылок. Если вам нужны эти значения, рассмотрите возможность его использования.

Если хук post-update включён, он по умолчанию запускает git update-server-info, чтобы поддерживать актуальность информации, используемой простыми транспортами (например, HTTP). Если вы публикуете репозиторий Git, доступный по HTTP, вероятно, следует включить этот хук.

Стандартный вывод и стандартный поток ошибок перенаправляются на git send-pack на другой стороне, поэтому сообщения для пользователя можно просто вывести с помощью echo.

reference-transaction

Этот хук вызывается любой командой Git, выполняющей обновление ссылок. Он запускается на этапах подготовки, готовности, фиксации или отмены транзакции ссылок, поэтому может вызываться несколько раз. Хук также поддерживает обновление символических ссылок.

Хук принимает ровно один аргумент, указывающий текущее состояние данной транзакции ссылок:

Для каждого обновления ссылки, добавленного в транзакцию, хук получает через стандартный ввод строку следующего формата:

<old-value> SP <new-value> SP <ref-name> LF

где <old-value> — старое имя объекта, переданное в транзакцию ссылок, <new-value> — новое имя объекта, которое будет сохранено в ссылке, а <ref-name> — полное имя ссылки. При принудительном обновлении ссылки независимо от её текущего значения или при создании новой ссылки <old-value> — это имя объекта, состоящее из одних нулей. Чтобы различить эти случаи, можно проверить текущее значение <ref-name> с помощью git rev-parse. В состоянии «preparing» символические ссылки не разрешаются: <ref-name> будет обозначать саму символическую ссылку, а не объект, на который она указывает.

При обновлении символических ссылок поля <old_value> и <new-value> могут обозначать ссылки, а не объекты. Ссылка обозначается префиксом ref:, например ref:<ref-target>.

Код возврата хука игнорируется во всех состояниях, кроме «preparing» и «prepared». В этих состояниях ненулевой код возврата приведёт к отмене транзакции. В этом случае хук не будет вызван в состоянии «aborted».

push-to-checkout

Этот хук вызывается командой git-receive-pack[1] при обработке git push и обновлении ссылок в репозитории, если отправка пытается обновить текущую выбранную ветку и для переменной конфигурации receive.denyCurrentBranch задано значение updateInstead. По умолчанию такая отправка отклоняется, если рабочее дерево и индекс удалённого репозитория отличаются от текущего выбранного коммита; если рабочее дерево и индекс соответствуют текущему коммиту, они обновляются в соответствии с новым конечным коммитом ветки. Этот хук предназначен для переопределения поведения по умолчанию.

Хук получает коммит, которым будет обновлена вершина текущей ветки. Он может завершиться с ненулевым кодом возврата, чтобы отклонить отправку (в этом случае он не должен изменять индекс или рабочее дерево). Также он может внести все необходимые изменения в рабочее дерево и индекс, чтобы привести их в требуемое состояние при обновлении вершины текущей ветки до нового коммита, а затем завершиться с нулевым кодом возврата.

Например, хук может просто выполнить git read-tree -u -m HEAD "$1", чтобы имитировать git fetch, выполняемый в обратном направлении с помощью git push, поскольку двухдеревная форма git read-tree -u -m по существу эквивалентна git switch или git checkout, которые переключают ветки, сохраняя локальные изменения в рабочем дереве, не конфликтующие с различиями между ветками.

pre-auto-gc

Этот хук вызывается командой git gc --auto (см. git-gc[1]). Он не принимает параметров; завершение этого скрипта с ненулевым кодом возврата приводит к прерыванию команды git gc --auto.

post-rewrite

Этот хук вызывается командами, переписывающими коммиты (git-commit[1] при вызове с параметром --amend и git-rebase[1]; однако инструменты, переписывающие историю целиком, например git-fast-import[1] или git-filter-repo, обычно его не вызывают!). Первый аргумент указывает команду, вызвавшую хук: в настоящее время это либо amend, либо rebase. В будущем могут передаваться дополнительные аргументы, зависящие от команды.

Хук получает список переписанных коммитов через stdin в формате

<old-object-name> SP <new-object-name> [ SP <extra-info> ] LF

Значение extra-info также зависит от команды. Если оно пустое, предшествующий SP также опускается. В настоящее время ни одна команда не передаёт extra-info.

Хук всегда запускается после автоматического копирования заметок (см. «notes.rewrite.<command>» в git-config[1]), поэтому он имеет доступ к этим заметкам.

Применяются следующие замечания, относящиеся к конкретным командам:

sendemail-validate

Этот хук вызывается командой git-send-email[1].

Он принимает следующие аргументы командной строки: 1. имя файла, содержащего текст отправляемого электронного письма. 2. Имя файла, содержащего SMTP-заголовки электронного письма.

SMTP-заголовки передаются точно так же, как они передаются агенту передачи почты (MTA) пользователя. Фактически электронное письмо, передаваемое MTA пользователя, состоит из содержимого $2, за которым следует содержимое $1.

Ниже приведён пример нескольких распространённых заголовков. Обратите внимание на регистр букв и структуру многострочных табуляций.

From: Example <from@example.com>
To: to@example.com
Cc: cc@example.com,
 A <author@example.com>,
 One <one@example.com>,
 two@example.com
Subject: PATCH-STRING

Завершение работы с ненулевым кодом состояния приводит к отмене выполнения git send-email до отправки электронных писем.

При выполнении хука задаются следующие переменные среды.

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

Образец хука sendemail-validate, поставляемый вместе с Git, проверяет, что все отправленные исправления (за исключением сопроводительного письма) можно применить поверх ветки по умолчанию вышестоящего репозитория без конфликтов. В нём оставлены заполнители для дополнительных этапов проверки, выполняемых после применения всех исправлений заданной серии.

fsmonitor-watchman

Этот хук вызывается, если параметр конфигурации core.fsmonitor имеет значение .git/hooks/fsmonitor-watchman или .git/hooks/fsmonitor-watchmanv2 в зависимости от используемой версии хука.

Версия 1 принимает два аргумента: версию (1) и время в прошедших наносекундах с полуночи 1 января 1970 года.

Версия 2 принимает два аргумента: версию (2) и токен, используемый для определения изменений, произошедших с момента, обозначенного токеном. Для watchman это будет идентификатор часов. Эта версия должна вывести в stdout новый токен, за которым следует NUL, а затем список файлов.

Хук должен вывести в stdout список всех файлов в рабочем каталоге, которые могли измениться с указанного времени. Логика должна быть включающей, чтобы не пропустить потенциальные изменения. Пути должны быть относительными к корню рабочего каталога и разделяться одним символом NUL.

Допускается включать файлы, которые фактически не изменились. Следует включать все изменения, в том числе создание и удаление файлов. При переименовании файлов следует включать как старое, так и новое имя.

Git ограничит набор проверяемых на изменения файлов и каталогов, проверяемых на наличие неотслеживаемых файлов, в соответствии с указанными путями.

Оптимизированный способ сообщить git, что «изменились все файлы», — вернуть имя файла /.

Код завершения определяет, будет ли git использовать данные хука для ограничения поиска. В случае ошибки git проверит все файлы и каталоги.

p4-changelist

Этот хук вызывается командой git-p4 submit.

Хук p4-changelist выполняется после того, как пользователь отредактировал сообщение списка изменений. Его можно пропустить с помощью параметра --no-verify. Он принимает один параметр — имя файла с предлагаемым текстом списка изменений. Завершение работы с ненулевым кодом состояния приводит к отмене выполнения команды.

Хук может редактировать файл списка изменений и использоваться для приведения текста к стандартному формату проекта. Его также можно использовать, чтобы отклонить отправку после проверки файла сообщения.

Подробности см. в git-p4 submit --help.

p4-prepare-changelist

Этот хук вызывается командой git-p4 submit.

Хук p4-prepare-changelist выполняется сразу после подготовки сообщения списка изменений по умолчанию и до запуска редактора. Он принимает один параметр — имя файла с текстом списка изменений. Завершение работы скрипта с ненулевым кодом состояния приводит к отмене процесса.

Назначение хука — редактировать файл сообщения на месте; параметр --no-verify не отключает его. Этот хук вызывается, даже если задан параметр --prepare-p4-only.

Подробности см. в git-p4 submit --help.

p4-post-changelist

Этот хук вызывается командой git-p4 submit.

Хук p4-post-changelist вызывается после успешного выполнения отправки в P4. Он не принимает параметров и предназначен главным образом для уведомления; он не может повлиять на результат действия git p4 submit.

Подробности см. в git-p4 submit --help.

p4-pre-submit

Этот хук вызывается командой git-p4 submit. Он не принимает параметров и данных из стандартного ввода. Завершение работы скрипта с ненулевым кодом состояния не позволяет запустить git-p4 submit. Его можно пропустить с помощью параметра командной строки --no-verify. Подробности см. в git-p4 submit --help.

post-index-change

Этот хук вызывается при записи индекса в read-cache.c функцией do_write_locked_index.

Первый аргумент, передаваемый хуку, указывает, обновляется ли рабочий каталог. Значение «1» означает, что рабочий каталог обновлён, а «0» — что рабочий каталог не обновлён.

Второй аргумент, передаваемый хуку, указывает, был ли обновлён индекс и мог ли измениться бит skip-worktree. Значение «1» означает, что биты skip-worktree могли быть обновлены, а «0» — что они не обновлялись.

При запуске хука только один аргумент должен иметь значение «1». Передача хуку значений «1», «1» невозможна.