Hooks

The hooks section maps git events to flows and/or jobs. This is what makes GitHooks run your QA tools automatically when you commit, push, or perform other git operations.

The hooks section is optional. Without it, you can still run flows and jobs manually from the CLI.

Basic syntax

'hooks' => [
    'pre-commit' => ['qa'],
    'pre-push'   => ['lint', 'test'],
],

Each hook references one or more flows (or jobs) by name. They are executed in order.

Supported events

GitHooks supports all standard client-side git hooks:

pre-commit, pre-push, commit-msg, prepare-commit-msg, post-commit, pre-merge-commit, post-merge, pre-rebase, post-checkout, post-rewrite, applypatch-msg, pre-applypatch, post-applypatch, and others.

The most commonly used are pre-commit (run QA before committing) and pre-push (run heavier checks before pushing).

Custom hook command

By default, the generated hook scripts call php vendor/bin/githooks hook:run <event>. If your environment uses a different PHP binary or path, set the command key:

'hooks' => [
    'command'    => 'php7.4 vendor/bin/githooks',
    'pre-commit' => ['qa'],
],

This generates .githooks/pre-commit with:

#!/bin/sh
# Generated by GitHooks — do not edit manually
php7.4 vendor/bin/githooks hook:run "$(basename "$0")"

Re-run githooks hook after changing this value to regenerate the scripts.

Conditional execution

Hook refs can include conditions that control when a flow/job is executed:

'hooks' => [
    'pre-commit' => [
        'qa',                                                      // always runs
        ['flow' => 'heavy', 'only-on' => ['main', 'develop']],    // only on these branches
        ['flow' => 'ci', 'exclude-on' => ['GH-*', 'temp/*']],     // skip on these branches
        ['job' => 'audit', 'only-files' => ['*.php', 'src/**']],   // only if matching files are staged
        ['job' => 'phpcs', 'only-files' => ['src/*'], 'exclude-files' => ['src/Generated/*']],
    ],
    'pre-push' => [
        ['flow' => 'fullAnalysis', 'only-on' => ['release/*']],
    ],
],

Condition keys

Key	Description
only-on	Array of branch names or glob patterns. The ref is skipped if the current branch doesn't match any pattern.
exclude-on	Array of branch names or glob patterns. The ref is skipped if the current branch matches any pattern. Always prevails over only-on. Can be used alone.
only-files	Array of file glob patterns. The ref is skipped if no staged files match any pattern.
exclude-files	Array of file glob patterns. Staged files matching any pattern are excluded from triggering execution. Always prevails over only-files. Can be used alone.
execution	String. Per-hook-ref execution mode override (full, fast, fast-branch).

When multiple conditions are present, they are AND-ed — all must be satisfied for the ref to execute.

Pattern syntax

All patterns use glob syntax, not regular expressions:

Pattern	Matches	Example
*	Any characters except / in file patterns	src/*.php matches src/User.php but not src/Models/User.php
*	Any characters including / in branch patterns	release/* matches release/v2.0
**	Zero or more directory levels (file patterns only)	src/**/*.php matches src/Models/User.php
?	Exactly one character	file?.php matches file1.php
[abc]	One character from the set	file[12].php matches file1.php
[!abc]	One character not in the set	file[!0-9].php matches fileA.php

Note

For file patterns, * does not cross directory separators. Use ** to match across directories.

Combining conditions

// Run only on release branches AND only when PHP files are staged
['flow' => 'deploy', 'only-on' => ['release/*'], 'only-files' => ['**/*.php']],

// Run on all branches except feature branches, exclude generated files
['flow' => 'ci', 'exclude-on' => ['GH-*'], 'exclude-files' => ['src/Generated/*']],

// Include with exclusions: release branches except beta
['flow' => 'deploy', 'only-on' => ['release/*'], 'exclude-on' => ['release/beta-*']],

Hook ref execution mode

Hook refs can specify an execution mode that overrides the default:

'hooks' => [
    'pre-commit' => [
        ['flow' => 'qa', 'execution' => 'fast'],          // staged files only
    ],
    'pre-push' => [
        ['flow' => 'qa', 'execution' => 'fast-branch'],   // branch diff
    ],
],

See Execution Modes for details on full, fast, and fast-branch.

Info

For pre-commit events, fast mode is activated automatically — you don't need to specify 'execution' => 'fast'.