Skip to content

2x ConfigurationFile

Jump to bottom
Wtyd edited this page Mar 29, 2026 · 4 revisions

The configuration file can be written in PHP (githooks.php) or YAML (githooks.yml) format. The PHP format is the default and the one generated by conf:init. The file must be in the root directory or in the qa/ directory.

Deprecation notice: The YAML format (githooks.yml) will be removed in version 3.x. It is recommended to migrate to the PHP format (githooks.php).

GitHooks searches for the configuration file in the following order (first match wins):

  1. ./githooks.php
  2. ./qa/githooks.php
  3. ./githooks.yml
  4. ./qa/githooks.yml

You can also specify a custom path with the -c or --config option (see Console Commands).

./
  qa/
    githooks.php # or here
  githooks.php # here (default)
  src/
  vendor/

The PHP format returns an associative array:

<?php
return [
    'Options' => [
        'execution' => 'full',
        'processes' => 1,
    ],
    'Tools' => [
        'phpstan',
        'phpcs',
    ],
    'phpstan' => [
        'executablePath' => 'vendor/bin/phpstan',
        'paths' => ['src'],
        'level' => 5,
    ],
    'phpcs' => [
        'executablePath' => 'vendor/bin/phpcs',
        'paths' => ['src', 'tests'],
        'standard' => 'PSR12',
    ],
];

The YAML format is equivalent:

Options:
    execution: full
    processes: 1

Tools:
    - phpstan
    - phpcs

phpstan:
    executablePath: vendor/bin/phpstan
    paths: [src]
    level: 5

phpcs:
    executablePath: vendor/bin/phpcs
    paths: [src, tests]
    standard: 'PSR12'

1. Structure

This file have 3 diferent parts:

  • Options (optional).
  • Tools (mandatory).
  • The configuration of the tools (the rest of the file). Mandatory for the tools setted in Tools tag.

1.1. Options

The Options tags may not be. In that case the default options will be established.

'Options' => [
    'execution' => 'fast',
    'processes' => 4,
],

1.1.1. Execution

The execution flag marks how GitHooks will run:

  • full (the default option): executes always all tools setted against all path setted for each tool. For example, you setted phpcs for run in src and app directories. The commit only contains modified files from database directory. Phpcs will check src and app directories even if no files in these directories have been modified.
  • fast: this option runs the tools only against files modified by commit.
    • This option only affects the following tools: phpcs, phpcbf, phpmd, phpstan, psalm, and parallel-lint. The rest of the tools will run as the full option.
    • WARNING!!! You must set the excludes of the tools either in githooks.php or in the configuration file of eath tool since this option overwrites the key paths of the tools so that they are executed only against the modified files.

Note (2.8.0): The global execution mode can be overridden per-tool by adding execution: full or execution: fast to each tool's configuration. See 1.3. Tools Configuration for details.

1.1.2. Processes

The processes tag is used to run multiple tools in multiple processes. It can also be overridden by Cli. The default number of processes is 1.

1.2. Tools

It is an array with the name of the tools that GitHooks will run. See the README.md.

Attention: the order in which the tools are is the order in which they will be executed.

1.3. Tools Configuration

The rest of the file are tags with name of the tools. The mandatory tools are those described in the Tools label.

Some options are common to all tools while others are specific to each tool. The common options are:

  • executablePath: where is the executable or binary for the tool. If not exists, GitHooks will interpret that the binary is in the global path.
  • otherArguments: flags or arguments that are not covered in GitHooks. GitHooks supports a few arguments but obviously, every tool has many and it is not possible to support all of them.
  • paths: the array of directories or files againts the tool will be runned. Security-checker, PHPUnit and Script do not have this option.
  • ignoreErrorsOnExit: boolean. Avoids error when the tool finds trouble. Default false. Present in all tools.
  • failFast: boolean. When true, if this tool fails, all remaining tools in the queue are skipped (shown as "⏩ toolName (skipped by failFast)" in output). Default false. When both failFast: true and ignoreErrorsOnExit: true are set on the same tool, failFast takes priority and ignoreErrorsOnExit is forced to false (a warning is generated).
  • execution: string. Overrides the global execution mode for this specific tool. Values: full or fast. When omitted, the tool inherits the global Options setting. Priority: CLI argument > per-tool setting > global Options > default (full). Only accelerable tools benefit from this setting (phpcs, phpcbf, phpmd, phpstan, psalm, parallel-lint).

Other options are specific to each tool. For example, for set phpcs:

'phpcs' => [
    'executablePath' => 'vendor/bin/phpcs',
    'execution' => 'fast',
    'paths' => ['src', 'tests'],
    'ignore' => ['vendor'],
    'standard' => 'PSR12',
    'otherArguments' => '--colors',
    'failFast' => true,
    'ignoreErrorsOnExit' => false,
],

There are no mandatory options for any tool. GitHooks support a subset of all possible arguments for each tool. More precise configuration is possible with each tool configuration file.

1.4. Phpstan

Argument Description Examples
executablePath String. Path to executable. Default 'phpstan' phpstan, 'vendor/bin/phpstan', 'path/to/phpstan'
paths Array. Paths or files against the tool will be executed ['./src'], ['./src', './app/MiFile.php']
otherArguments String. Flags or arguments that are not covered in GitHooks '--ansi', '--debug'
ignoreErrorsOnExit Boolean. Avoids error when the tool found trouble. Default false. true, false
config String. Path to configuration file 'phpstan.neon', 'path/to/phpstan.neon'
memory-limit String. Set the php memory limit while phpstan is running '1M', '2000M', '1G'
level Integer. Default 0. Max depends on PHPStan version (9 for 1.x, 10 for 2.x). 0, 1, 5, 8
error-format String. Output format for errors. 'table', 'json', 'raw', 'github', 'gitlab'
no-progress Boolean. Suppress progress output. Default false. true, false
clear-result-cache Boolean. Clear result cache before analysis. Default false. true, false
failFast Boolean. Stop remaining tools on failure. Default false. true, false

1.5. Parallel-lint

Argument Description Examples
executablePath String. Path to executable. Default 'parallel-lint' parallel-lint, 'vendor/bin/parallel-lint', 'path/to/parallel-lint'
paths Array. Paths or files against the tool will be executed [src], [src, './app/MiFile.php']
otherArguments String. Flags or arguments that are not covered in GitHooks '--colors'
ignoreErrorsOnExit Boolean. Avoids error when the tool found trouble. Default false. true, false
exclude Array. Paths or files to exclude. [vendor], [vendor, './app/MiFile.php']
jobs Integer. Number of parallel jobs (-j flag). 10
failFast Boolean. Stop remaining tools on failure. Default false. true, false

1.6. Phpcs and Phpcbf

Argument Description Examples
executablePath String. Path to executable. Default 'phpcs' or 'phpcbf' phpcs, 'vendor/bin/phpcbf', 'path/to/phpcs'
paths Array. Paths or files against the tool will be executed [src], [src, './app/MiFile.php']
otherArguments String. Flags or arguments that are not covered in GitHooks '--colors', '--colors --encoding=utf-8'
ignoreErrorsOnExit Boolean. Avoids error when the tool found trouble. Default false. true, false
standard String. Rules or configuration file with the rules. 'PSR12', 'Squizs', 'Generic', 'PEAR', 'myrules.xml'
ignore Array. Paths or files to exclude. [vendor], [vendor, './app/MiFile.php']
error-severity Integer. Level of error to detect. 1, 5
warning-severity Integer. Level of warning to detect. 5, 7, 9
cache Boolean flag. Enable result caching. true
no-cache Boolean flag. Disable caching (overrides cache). true
report String. Report format. 'full', 'summary', 'json', 'csv', 'checkstyle'
parallel Integer. Number of parallel file processing. 2, 4
usePhpcsConfiguration Boolean. Grabs the phpcs setting. Default false. Only for phpcbf true, false
failFast Boolean. Stop remaining tools on failure. Default false. true, false

The usePhpcsConfiguration option is used to simplify the configuration of phpcbf as it will normally use the same options as phpcs. Examples:

'phpcs' => [
    'executablePath' => 'vendor/bin/phpcs',
    'paths' => ['src', 'tests'],
    'ignore' => ['vendor'],
    'standard' => 'PSR12',
],
'phpcbf' => [
    'usePhpcsConfiguration' => true,
],

Phpcbf is setted exactly like phpcs. The executablePath for phpcbf will be vendor/bin/phpcbf. usePhpcsConfiguration replaces phpcs for phpcbf in the executablePath option.

'phpcs' => [
    'executablePath' => 'vendor/bin/phpcs',
    'paths' => ['src', 'tests'],
    'ignore' => ['vendor'],
    'standard' => 'PSR12',
    'error-severity' => 5,
],
'phpcbf' => [
    'usePhpcsConfiguration' => true,
    'error-severity' => 1,
    'paths' => ['src', 'tests', 'app'],
],

Phpcbf takes the phpcs configuration but overrides the variables paths and error-severity.

Phpcbf Auto-Staging

When phpcbf fixes files during a pre-commit hook run (exit code 1 = fixes applied), GitHooks automatically re-stages the fixed files to git. This ensures that the corrected files are included in the commit without requiring a manual git add. Deleted files are excluded from re-staging. No configuration is needed — this is automatic behavior.

1.7. Phpmd

Argument Description Examples
executablePath String. Path to executable. Default 'phpmd' phpmd, 'vendor/bin/phpmd', 'path/to/phpmd'
paths Array. Paths or files against the tool will be executed ['./src'], ['./src', './app/MiFile.php']
otherArguments String. Flags or arguments that are not covered in GitHooks '--strict'
ignoreErrorsOnExit Boolean. Avoids error when the tool found trouble. Default false. true, false
rules String. Rules or configuration file with the rules. 'controversial,codesize', 'naming', 'myrules.xml'
exclude Array. Paths or files to exclude. ['./vendor'], ['./vendor', './app/MiFile.php']
cache Boolean. Enable caching (PHPMD 2.13.0+). Default false. true
cache-file String. Custom cache file path. '.phpmd.cache'
cache-strategy String. Cache strategy. 'content', 'timestamp'
suffixes String. File suffixes to check (comma-separated). 'php', 'php,phtml'
baseline-file String. Baseline file to ignore known violations. 'phpmd-baseline.xml'
failFast Boolean. Stop remaining tools on failure. Default false. true, false

1.8. Phpcpd

Argument Description Examples
executablePath String. Path to executable. Default 'phpcpd' phpcpd, 'vendor/bin/phpcpd', 'path/to/phpcpd'
paths Array. Paths or files against the tool will be executed [src], [src, './app/MiFile.php']
exclude Array. Paths or files to exclude. [vendor], [vendor, './app/MiFile.php']
otherArguments String. Flags or arguments that are not covered in GitHooks '--fuzzy'
ignoreErrorsOnExit Boolean. Avoids error when the tool found trouble. Default false. true, false
min-lines Integer. Minimum number of identical lines to detect as copy-paste. 5, 10
min-tokens Integer. Minimum number of identical tokens to detect as copy-paste. 70, 100
failFast Boolean. Stop remaining tools on failure. Default false. true, false

1.9. Security-checker

Note: local-php-security-checker is deprecated. It is recommended to use composer audit instead, which is built into Composer 2.4+ and does not require any additional binary. Set executablePath to composer audit:

'security-checker' => [
    'executablePath' => 'composer audit',
    'otherArguments' => '--format=json',
],
Argument Description Examples
executablePath String. Path to executable. Default 'local-php-security-checker' 'composer audit', 'local-php-security-checker'
otherArguments String. Flags or arguments that are not covered in GitHooks '--format=json', '-format json'
ignoreErrorsOnExit Boolean. Avoids error when the tool found trouble. Default false. true, false
failFast Boolean. Stop remaining tools on failure. Default false. true, false

1.10. PHPUnit

Argument Description Examples
executablePath String. Path to executable. Default 'phpunit' phpunit, 'vendor/bin/phpunit', 'php7.1 vendor/bin/phpunit'
group String or Array. Run only tests from the specified group(s) 'integration', ['integration', 'unit']
exclude-group String or Array. Exclude tests from the specified group(s) 'slow', ['slow', 'quarantine']
filter String. Filter which tests to run by regex pattern 'testSomething', 'MyClassTest'
configuration String. Path to PHPUnit XML configuration file 'phpunit.xml', 'path/to/phpunit.xml'
log-junit String. Log test execution in JUnit XML format 'junit.xml', 'path/to/junit.xml'
otherArguments String. Flags or arguments that are not covered in GitHooks '--colors=always', '--colors=always --verbose'
ignoreErrorsOnExit Boolean. Avoids error when the tool found trouble. Default false. true, false
failFast Boolean. Stop remaining tools on failure. Default false. true, false

Example:

'phpunit' => [
    'executablePath' => 'vendor/bin/phpunit',
    'group' => 'integration',
    'exclude-group' => 'slow',
    'configuration' => 'phpunit.xml',
    'log-junit' => 'junit.xml',
    'otherArguments' => '--colors=always',
],

1.11. Psalm

Argument Description Examples
executablePath String. Path to executable. Default 'psalm' psalm, 'vendor/bin/psalm'
paths Array. Paths or files against the tool will be executed ['src'], ['src', 'app']
config String. Path to Psalm XML configuration file 'psalm.xml', 'qa/psalm.xml'
memory-limit String. Set the php memory limit while psalm is running '512M', '1G'
threads Integer. Number of threads for parallel analysis 1, 4, 8
no-diff Boolean. Disable diff mode (analyze all files) true, false
output-format String. Output format 'console', 'json', 'xml', 'checkstyle', 'junit'
plugin String. Path to a Psalm plugin 'path/to/plugin.php'
use-baseline String or Boolean. Path to baseline file to ignore known issues 'psalm-baseline.xml', false
report String. Generate a report file (format inferred from extension) 'psalm-report.xml', 'report.txt'
otherArguments String. Flags or arguments that are not covered in GitHooks '--no-progress', '--no-progress --show-info=true'
ignoreErrorsOnExit Boolean. Avoids error when the tool found trouble. Default false. true, false
failFast Boolean. Stop remaining tools on failure. Default false. true, false

Example:

'psalm' => [
    'executablePath' => 'vendor/bin/psalm',
    'config' => 'qa/psalm.xml',
    'memory-limit' => '1G',
    'threads' => 4,
    'paths' => ['src', 'app'],
    'otherArguments' => '--no-progress',
],

1.12. Script

Generic tool type for running any QA tool not natively supported by GitHooks. Unlike other tools, executablePath is required — there is no default value.

Argument Description Examples
name String. Custom alias for the script tool. Optional. When set, use this name in the Tools array and CLI instead of 'script'. Cannot conflict with existing supported tool names. 'php-cs-fixer', 'infection', 'pdepend'
executablePath String. Path to executable. Required. 'vendor/bin/php-cs-fixer', 'vendor/bin/infection'
otherArguments String. Flags or arguments to pass to the executable 'fix --dry-run', '--min-msi=80 --threads=4'
ignoreErrorsOnExit Boolean. Avoids error when the tool found trouble. Default false. true, false
failFast Boolean. Stop remaining tools on failure. Default false. true, false

Example without name:

'script' => [
    'executablePath' => 'vendor/bin/php-cs-fixer',
    'otherArguments' => 'fix --dry-run --config=.php-cs-fixer.php',
    'ignoreErrorsOnExit' => false,
],

The output will display the executablePath value as the tool name (e.g. vendor/bin/php-cs-fixer - OK).

Example with name:

'Tools' => [
    'phpcs',
    'php-cs-fixer',  // use the custom name instead of 'script'
],

// The configuration key is always 'script', with the 'name' attribute inside:
'script' => [
    'name' => 'php-cs-fixer',
    'executablePath' => 'vendor/bin/php-cs-fixer',
    'otherArguments' => 'fix --dry-run --config=.php-cs-fixer.php',
    'ignoreErrorsOnExit' => false,
],

Or in YAML:

Tools:
  - phpcs
  - php-cs-fixer  # use the custom name instead of 'script'

# The configuration key is always 'script', with the 'name' attribute inside:
script:
    name: php-cs-fixer
    executablePath: vendor/bin/php-cs-fixer
    otherArguments: 'fix --dry-run --config=.php-cs-fixer.php'
    ignoreErrorsOnExit: false

GitHooks internally resolves the alias: the Tools array and the CLI use the custom name, but the configuration section is always written under script.

When name is set, you can use the custom name in the CLI:

githooks tool php-cs-fixer  # instead of 'githooks tool script'

Note: The custom name cannot conflict with existing supported tool names (phpcs, phpcbf, phpstan, etc.). An error is thrown if a conflict is detected.

2. Create Configuration File

Before first run you must create and set the configuration file. For this you must run the command githooks conf:init. It copies a githooks.php file template to the root of the project with all the options commented of each tool.

Once created we can move it to qa/githooks.php or leave it in the project root. The YAML format (githooks.yml) is also supported.

3. Check Configuration File

To make sure that when you finish configuring the configuration file, all the options are valid, you can launch the command githooks conf:check:

conf:check

GitHooks will be able to run as long as it doesn't have any errors. Warnings allow GitHooks to run but all configured tools may not run or some may work unexpectedly.

Documentation

2.x Documentation
3.x Documentation (current)

Contributing

Clone this wiki locally