Skip to content

2x ConfigurationFile

Jump to bottom
Wtyd edited this page Mar 26, 2026 · 2 revisions

The configuration file githooks.yml must be in root directory or in qa/ directory

./
  qa/
    githooks.yml # here or
  githooks.yml # here
  src/
  vendor/

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, phpmd, phpstan, 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.yml 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.

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 is the only tool that does not have this option.

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

phpcs:
    executablePath: vendor/bin/phpcs
    paths: [src, tests]
    ignore: [vendor]
    standard: 'PSR12'
    otherArguments: '--report=summary --parallel=2'

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 '--no-progress', '--no-progress --ansi'
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 9. 0, 1, 5, 8

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']

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 '--report=summary', '--report=summary --parallel=2'
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
usePhpcsConfiguration Boolean. Grabs the phpcs setting. Default false. Only for phpcbf 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:
  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 replace phpcs for phpcbf in the executablePath option.

phpcs:
  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 override the variables paths and error-severity.

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']

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 '--min-lines=5'
ignoreErrorsOnExit Boolean. Avoids error when the tool found trouble. Default false. true, false

1.9. Security-checker

Argument Description Examples
executablePath String. Path to executable. Default 'local-php-security-checker' local-php-security-checker, 'path/to/local-php-security-checker'
otherArguments String. Flags or arguments that are not covered in GitHooks '-format json'
ignoreErrorsOnExit Boolean. Avoids error when the tool found trouble. 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

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

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
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

Example:

'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).

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.yml file template to the root of the project with all the options commented of each the tool.

Once created we can move it to qa/githookks.yml or leave it in the project root.

3. Check Configuration File

To make sure that when you finish configuring the githooks.yml, all the options are valid, you can launch the command githhooks 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 (actual)
3.x Documentation (work in progress)

Contributing

Clone this wiki locally