git-hook

Имя

git-hook — запуск хуков Git

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

git hook run [--allow-unknown-hook-name] [--ignore-missing] [--to-stdin=<path>] [(-j|--jobs) <n>]
        <hook-name> [-- <hook-args>]
git hook list [--allow-unknown-hook-name] [-z] [--show-scope] <hook-name>

Описание

Интерфейс командной строки для запуска хуков Git (см. githooks[5]), предназначенный для использования другими командами Git, работающими со сценариями.

Эта команда анализирует файлы конфигурации по умолчанию на предмет групп настроек, например:

[hook "linter"]
  event = pre-commit
  command = ~/bin/linter --cpp20

В этом примере [hook "linter"] представляет один сценарий — ~/bin/linter --cpp20, — которым могут совместно пользоваться многие репозитории и даже несколько событий хуков, если это уместно.

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

[hook "linter"]
  event = pre-commit
  command = ~/bin/linter --cpp20
[hook "spellcheck"]
  event = commit-msg
  command = ~/bin/spellchecker

При такой конфигурации, когда вы выполняете git commit, сначала у ~/bin/linter --cpp20 будет возможность проверить файлы, которые нужно закоммитить (во время события хука pre-commit), а затем у ~/bin/spellchecker будет возможность проверить сообщение коммита (во время события хука commit-msg).

Команды запускаются в том порядке, в котором Git обнаруживает связанные с ними настройки hook.<friendly-name>.event при анализе конфигурации (см. git-config[1]). Можно добавить несколько настроек hook.linter.event, но допустимо только одно событие hook.linter.command — Git выбирает команду по принципу «последняя настройка имеет приоритет».

Поэтому, если вы хотите запускать линтер как при коммите, так и при отправке изменений, настройте его следующим образом:

[hook "linter"]
  event = pre-commit
  event = pre-push
  command = ~/bin/linter --cpp20

При такой конфигурации Git запустит ~/bin/linter --cpp20 перед созданием коммита (во время pre-commit), а также перед отправкой изменений (во время pre-push).

Если же вы хотите запускать линтер и средство обнаружения утечки секретов только во время события хука «pre-commit», настройте их следующим образом:

[hook "linter"]
  event = pre-commit
  command = ~/bin/linter --cpp20
[hook "no-leaks"]
  event = pre-commit
  command = ~/bin/leak-detector

При такой конфигурации перед созданием коммита (во время pre-commit) Git сначала запустит ~/bin/linter --cpp20, а затем — ~/bin/leak-detector. Принимая решение о продолжении создания коммита, Git оценит вывод каждой команды.

Полный список событий хуков, которые можно указать для hook.<friendly-name>.event, и описание вызова хуков при этих событиях см. в githooks[5].

Git игнорирует любые настройки hook.<friendly-name>.event, в которых указано неизвестное ему событие. Это сделано для того, чтобы инструменты-обертки Git могли использовать инфраструктуру хуков для запуска собственных хуков; дополнительные сведения см. в разделе «ОБЕРТКИ».

Как правило, если инструкции предлагают добавить сценарий в .git/hooks/<hook-event>, вместо этого его можно указать в конфигурации, выполнив:

git config set hook.<some-name>.command <path-to-script>
git config set --append hook.<some-name>.event <hook-event>

Так вы сможете использовать сценарий в нескольких репозиториях. То есть cp ~/my-script.sh ~/project/.git/hooks/pre-commit можно заменить на:

git config set hook.my-script.command ~/my-script.sh
git config set --append hook.my-script.event pre-commit

Подкоманды

run

Запускает хуки, настроенные для <hook-name>, в порядке их обнаружения при анализе конфигурации. Хук из каталога хуков, соответствующий <hook-name> по умолчанию, запускается последним. Поддерживаемые имена хуков см. в githooks[5].

Любые позиционные аргументы для хука необходимо передавать после обязательного -- (или --end-of-options, см. gitcli[7]). Аргументы, которые могут ожидать хуки (если таковые имеются), описаны в githooks[5].

list [-z] [--show-scope]

Выводит список хуков, которые будут запущены при событии <hook-name>. Если для этого события не настроено ни одного хука, выводит предупреждение и возвращает 1. Используйте -z, чтобы завершать строки вывода нулевым байтом вместо символа новой строки.

Параметры

--allow-unknown-hook-name

По умолчанию команды git hook run и git hook list завершатся с ошибкой, если Git не знает событие хука <hook-name> (список известных хуков см. в githooks[5]). Это помогает выявлять опечатки, например prereceive вместо предполагаемого pre-receive. Передайте этот флаг, чтобы разрешить неизвестные имена хуков.

--to-stdin

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

--ignore-missing

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

-z

Завершает строки вывода команды «list» нулевым байтом вместо символа новой строки.

--show-scope

Для команды «list»: добавляет перед понятным именем каждого настроенного хука область конфигурации, отделенную табуляцией (например, local, global, system), используя стиль вывода команды git config --show-scope. На традиционные хуки из каталога хуков это не влияет.

-j

--jobs

Допустим только для run.

Указывает, сколько хуков запускать одновременно. Если этот флаг не указан, используется значение настройки hook.jobs; см. git-config[1]. Если не указано ни то ни другое, по умолчанию используется 1 (последовательное выполнение).

Если значение больше 1, оно переопределяет настройку hook.<friendly-name>.parallel для отдельных хуков, позволяя всем хукам этого события выполняться одновременно, даже если для них не задано параллельное выполнение.

Некоторые хуки всегда выполняются последовательно независимо от этого флага и настройки hook.jobs, поскольку Git знает, что их нельзя безопасно запускать параллельно: applypatch-msg, pre-commit, prepare-commit-msg, commit-msg, post-commit, post-checkout и push-to-checkout.

Обертки

git hook run разработана так, чтобы инструменты-обертки Git могли легко настраивать и запускать хуки с помощью инфраструктуры хуков Git. Можно передавать аргументы и стандартный ввод через командную строку, а также задавать параллельное или последовательное выполнение, если пользователь настроил несколько хуков.

Предположим, ваша обертка должна поддерживать хук с именем «mywrapper-start-tests». Пользователи могут указать свои хуки следующим образом:

[hook "setup-test-dashboard"]
  event = mywrapper-start-tests
  command = ~/mywrapper/setup-dashboard.py --tap

Затем в инструменте mywrapper можно вызвать любые хуки, настроенные пользователями, выполнив:

git hook run --allow-unknown-hook-name mywrapper-start-tests \
  # providing something to stdin
  --stdin some-tempfile-123 \
  # execute multiple hooks in parallel
  --jobs 3 \
  # plus some arguments of your own...
  -- \
  --testname bar \
  baz

Выбирайте названия событий хуков для своей обертки так, чтобы они как можно меньше пересекались с встроенными хуками Git (см. githooks[5]): вероятность того, что Git добавит встроенное событие хука с именем mywrappertool-validate-commit, гораздо ниже, чем для события с именем validate-commit. Если Git начнет использовать событие хука с тем же именем, что и хук вашей обертки, он может вызывать хуки пользователей непредусмотренным и неподдерживаемым образом.

Конфигурация

hook.<friendly-name>.command: Команда, выполняемая для hook.<friendly-name>. <friendly-name> — уникальное имя, идентифицирующее этот хук. События хуков, запускающие команду, задаются настройками hook.<friendly-name>.event. Значением может быть путь к исполняемому файлу или однострочная команда оболочки. Если для одного и того же <friendly-name> указано несколько значений, используется только последнее разобранное значение.
hook.<friendly-name>.event: События хуков, запускающие hook.<friendly-name>. Значение — имя события хука, например «pre-commit» или «update». (Полный список событий хуков см. в githooks[5].) При наступлении указанного события выполняется связанная настройка hook.<friendly-name>.command. Этот ключ может иметь несколько значений. Чтобы запускать hook.<friendly-name> при нескольких событиях, укажите ключ несколько раз. Пустое значение сбрасывает список событий, удаляя все ранее заданные события для hook.<friendly-name>.

<friendly-name> не должно совпадать с именем известного события хука (например, не используйте hook.pre-commit.event). Использование имени известного события в качестве понятного имени приводит к фатальной ошибке, поскольку создает неоднозначность с настройками hook.<event>.enabled и hook.<event>.jobs. Для неизвестных имен событий выдается предупреждение, если <friendly-name> совпадает со значением события.
hook.<friendly-name>.enabled: Определяет, включен ли хук hook.<friendly-name>. По умолчанию — true. Установите значение false, чтобы отключить хук, не удаляя его конфигурацию. Это особенно полезно, когда хук задан в системном или глобальном файле конфигурации, но его нужно отключить для конкретного репозитория.
hook.<friendly-name>.parallel: Определяет, может ли хук hook.<friendly-name> выполняться параллельно с другими хуками для того же события. По умолчанию — false. Установите значение true только в том случае, если сценарий хука можно безопасно выполнять одновременно с другими хуками для того же события. Если для какого-либо хука события значение не равно true, все хуки этого события выполняются последовательно независимо от настройки hook.jobs. Эту настройку нужно задавать только для настроенных (именованных) хуков. Для традиционных хуков из каталога хуков это не требуется: они выполняются параллельно, если эффективное число заданий больше 1.
hook.<event>.enabled: Включает или отключает все хуки для события хука <event>. Если задано значение false, для этого события не запускается ни один хук, независимо от настроек hook.<friendly-name>.enabled отдельных хуков. По умолчанию — true.

Примечание об именовании: <event> должно быть именем события (например, pre-commit), а не понятным именем хука. Поскольку использовать имя известного события в качестве понятного имени запрещено (см. описание hook.<friendly-name>.event выше), настройки .enabled для известного события на уровне события и отдельного хука не могут быть неоднозначными. Для неизвестных событий, если понятное имя совпадает с именем события вопреки предупреждению, настройка .enabled трактуется только как настройка отдельного хука.
hook.<event>.jobs: Задает количество хуков, которые можно одновременно запускать для события хука <event> (например, hook.post-receive.jobs = 4). Переопределяет hook.jobs для этого конкретного события. Действуют те же ограничения параллельного выполнения: эта настройка не влияет на выполнение, если для всех настроенных хуков события значение hook.<friendly-name>.parallel не равно true. Установите значение -1, чтобы использовать количество доступных ядер ЦП. Значение должно быть положительным целым числом или -1; ноль отклоняется с предупреждением.

Примечание об именовании: хотя этот ключ похож на hook.<friendly-name>.* (настройку отдельного хука), <event> должно быть именем события, а не понятным именем хука. Компонент ключа сохраняется буквально, а во время выполнения поиск выполняется по имени события без преобразования между двумя пространствами имен. Ключ вида hook.my-hook.jobs сохраняется как "my-hook", но во время выполнения поиск производится по имени события (например, "post-receive"), поэтому hook.my-hook.jobs молча игнорируется, даже если для этого события зарегистрировано my-hook. Для настройки hook.<event>.jobs используйте hook.post-receive.jobs или любое другое допустимое имя события.
hook.jobs: Задает количество хуков, которые можно одновременно запускать при параллельном выполнении хуков. Если значение не указано, по умолчанию используется 1 (последовательное выполнение). Установите значение -1, чтобы использовать количество доступных ядер ЦП. Значение можно переопределить отдельно для каждого события с помощью hook.<event>.jobs. Некоторые хуки всегда выполняются последовательно независимо от этой настройки, поскольку они работают с общими данными и не могут безопасно выполняться параллельно:

applypatch-msg

prepare-commit-msg

commit-msg

Получают файл сообщения коммита и могут изменять его на месте.

pre-commit

post-checkout

push-to-checkout

post-commit

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

Эта настройка не влияет на выполнение, если для всех настроенных хуков события значение hook.<friendly-name>.parallel не равно true.

Для хуков pre-push, которые обычно выводят stdout и stderr отдельно, установка значения больше 1 (или передача -j) объединит stdout со stderr, чтобы обеспечить корректное разделение параллельного вывода.

См. также

githooks[5]

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