Conditional Hooks¶

Run different tools depending on the branch, staged files, or both.

Run only on specific branches¶

'hooks' => [
    'pre-push' => [
        ['flow' => 'full', 'only-on' => ['main', 'develop']],
    ],
],

The full flow only runs when pushing from main or develop.

Skip on feature branches¶

'hooks' => [
    'pre-commit' => [
        'qa',                                                    // always runs
        ['flow' => 'heavy', 'exclude-on' => ['GH-*', 'temp/*']], // skip on these
    ],
],

Run only when PHP files are staged¶

'hooks' => [
    'pre-commit' => [
        ['flow' => 'php-qa', 'only-files' => ['**/*.php']],
        ['job' => 'eslint', 'only-files' => ['resources/js/**']],
    ],
],

The PHP QA flow only runs if PHP files are staged. The ESLint job only runs if JavaScript files are staged.

Combine conditions¶

Conditions are AND-ed — all must be satisfied:

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

Exclude prevails over include¶

When a branch or file matches both only-* and exclude-*, it is excluded:

// All release branches EXCEPT beta releases
['flow' => 'deploy', 'only-on' => ['release/*'], 'exclude-on' => ['release/beta-*']],

// All PHP files EXCEPT generated ones
['job' => 'phpcs', 'only-files' => ['src/**/*.php'], 'exclude-files' => ['src/Generated/**']],

Pattern syntax¶

All patterns use glob syntax. For file patterns, * does not cross directories — use ** for recursive matching:

Pattern	Matches
`src/*.php`	`src/User.php` but not `src/Models/User.php`
`src/*/.php`	`src/User.php`, `src/Models/User.php`, `src/A/B/C.php`
`release/*`	`release/v2.0` (branch patterns: `*` crosses `/`)

See the Glob syntax reference for the full pattern reference.

Not the same as `--exclude-pattern`¶

exclude-files here is a gating condition: the hook entry either runs or doesn't, depending on whether the staged file set matches the patterns.

The --exclude-pattern CLI flag (with the same glob syntax) is a filter on top of --files / --files-from: it drops paths from the user-provided input list before per-job filtering. Use --exclude-pattern from the command line, exclude-files inside hooks.<event> config. See How-To: --files / --files-from.