Skip to content

3x ConfigurationFile

Jump to bottom
Wtyd edited this page Jun 6, 2024 · 1 revision

1. 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 with some examples.

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

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

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

2. Structure

This file have 3 diferent parts:

  • Flows: a flow is a group of jobs that run together.
  • Hooks: set which flow or job runs on which git hook.
  • Jobs: a single task.

3. Flows

A flow is a group of jobs that will be executed with a certain configuration.

flows:
    myPrecommit:
        options:
            fail-fast: true
        jobs:
        - phpcbf_src
        - phpcs_src
        - phpmd_app
        - phpmd_src

The jobs will be executed one by one and in order. Also, a flow has options. This options are stablished locally or globally for all flows. Local configuration override global configuration:

flows:
    options:
      fail-fast: false
      processes: 2

    myPrecommit:
        options:
            fail-fast: true
        jobs:
        - phpcbf_src
        - phpcs_src
        - phpmd_app
        - phpmd_src

    myPrepush:
        jobs:
        - otherJob

Internally is like this:

flows:
    myPrecommit:
        options:
            processes: 2
            fail-fast: true # override global option fail-fast 
        jobs:
        - phpcbf_src
        - phpcs_src
        - phpmd_app
        - phpmd_src

    myPrepush:
        options:
          processes: 2  # gets options from global configuration
          fail-fast: false
        jobs:
        - otherJob

In this case myPrecommit override fail-fast option but not processes.

4. Hooks

In this section you tell the tool which flow we will execute when a Git event occurs. The supported events are Client-Side Hooks

hooks:
    pre-commit: myPrecommitFlow
    pre-push: myPrepushFlow

You can also run a custom script:

hooks:
    pre-commit: myCustomScript.php

See the commands section for more details.

When you run the hooks command it will set the hooks, ie which flow or script should be executed for each git event.

5. Jobs

Los jobs describen una tarea concreta.

phpmdSrc: # Los nombres de los jobs en snake_case, camelCase, StudlyCase..
    type: phpmd
    executablePath: vendor/bin/phpmd
    paths: ['./src/']
    rules: './qa/phpmd-ruleset.xml'  # predefined rules cleancode,codesize,controversial,design,naming,unusedcode
    exclude: [vendor]

Jobs must have a type. The allowed types are the supported tools (phpmd, phpcs, phpcbf, phpcpd, parallel-lint, phpstan and security-checker) or custom (to customize a script). Depending on the type, it will support some keys or others. See the Keyword Reference.

5.1. Quickly Guide

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

  • executablePath: path to binary of 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 a job type phpcs or phpcbf:

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

5.2. The Custom Type

This type of job is special. It makes GitHooks adaptable to any kind of circumstance:

  • Allows running tools not supported by GitHooks.
  • Allows you to run any script in bash, javascript or any language.

This way you can customize your hooks to the level you want and allows GitHooks to be the only tool needed to execute hooks in hybrid projects (php/javascript, for example).

backend_tests:
    type: custom
    script: 'vendor/bin/phpunit --colors true --exclude-group quarantine'

lintFrontEnd:
    type: custom
    script: node pretier --

The custom type has just two keys:

  • script. It is the command you want to execute.
  • ignoreErrorsOnExit. Avoids error when the job found trouble.

6. Check Configuration File

To make sure that when you finish configuring the githooks.yml, all the options are valid, you can run githhooks conf:check command:

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.

7. Keyword Reference

Below is a complete guide to all the options. The keys jobs, hooks and flows are supported in the file root. The order is indistinct but they cannot be more than once.

7.1. Jobs

The keys that each job admits depend on the type of job in question. The only mandatory key for this is just type; the rest may not exist.

Important: the lack of any key can cause the job to fail. For example, running a job of type: phpcs without the standard key. The standard might be set in the tool's configuration file or it might not. If there is no standard, an error will be obtained from the tool.

7.1.1. Common Keywords

Las siguientes keys son comunes a casi todos los tipos de job.

Keyword Description Examples
type String. The type depends on whether the job has some keys or others. Mandatory phpcs, phpcbf, phpmd,parallel-lint,
phpcpd, security-checker, custom
executablePath String. Path to executable. For non-custom types, the global path is searched if it is not informed. phpcpd, 'vendor/bin/phpcs', '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. '--min-lines=5'
ignoreErrorsOnExit Boolean. The job ends with exit code 0 even if some problem is detected. Default false. true, false

A continuación se describen las posibles keys por cada tipo de job.

7.1.2. Type 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. The job ends with exit code 0 even if some problem is detected. 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 (It depends on the version of phpstan). 0, 1, 5, 8

7.1.3. Type 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. The job ends with exit code 0 even if some problem is detected. Default false. true, false
exclude Array. Paths or files to exclude. [vendor], [vendor, './app/MiFile.php']

7.1.4. Types 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. The job ends with exit code 0 even if some problem is detected. 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:

jobs:
    phpcs_job:
        type: phpcs
        executablePath: vendor/bin/phpcs
        paths: [src, tests]
        ignore: [vendor]
        standard: 'PSR12'

    phpcbf_job:
        type: 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.

jobs:
    phpcs_job:
        type: phpcs
        executablePath: vendor/bin/phpcs
        paths: [src, tests]
        ignore: [vendor]
        standard: 'PSR12'
        error-severity: 5

    phpcbf_job:
        type: phpcbf
        usePhpcsConfiguration: true
        error-severity : 1
        paths: [src, tests, app]

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

7.1.5. Type 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. The job ends with exit code 0 even if some problem is detected. 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']

7.1.6. Type 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. The job ends with exit code 0 even if some problem is detected. Default false. true, false

7.1.7. Type 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. The job ends with exit code 0 even if some problem is detected. Default false. true, false

7.2. Flows

A flow is a group of jobs that run together. A job can be executed in more than one flow.

Argument Description Examples
options Array. Flow execution options. Possible values: execution, processes, fail-fast, ignoreErrorsOnExit full, fast
jobs Array. Name of jobs setted for the flow. Configured jobs
Argument Description Examples
execution String. Mode in which GitHooks are executed. Default full. full, fast
processes Integer. Execute the jobs of the flow in multiple processes. Default 1 1, 2, 3...
fail-fast Boolean. The flow ends with an error when a job fails. Default false. true, false
ignoreErrorsOnExit Boolean. The flow ends with exit code 0 even if any job encounters a problem.
(Applies ignoreErrorsOnExit to all jobs). Default false.		 true, false

7.2.1. Execution

The execution flag marks how GitHooks will run:

  • full (the default option): executes always all jobs setted against all path setted for each tool. For example, you setted a phpcs job 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 jobs only against files modified by commit.
    • This mode only affects the following type of jobs: phpcs, phpmd, phpstan, and parallel-lint. All other types of jobs will run as the full option.
    • WARNING!!! You must set the excludes/ignores 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.

7.2.2. Fail-fast and IgnoreErrorsOnExit

Be ware that the fail-fast option is not compatible with the ignoreErrorsOnExit option. If you set fail-fast to true and ignoreErrorsOnExit to true the ignoreErrorsOnExit will be ignored. However, it is compatible with ignoreErrorsOnExit option in jobs level. In this case, the job setted with ignoreErrorsOnExit to true will not end the flow even if it fails.

Besides, the ignoreErrorsOnExit on the flow section will override the ignoreErrorsOnExit for all the jobs of this flow.

flows:
    myFirstFlow:
        options:
            execution: full
            ignoreErrorsOnExit: true
        jobs: [first_job, second_job]

    mySecondFlow:
        options:
            processes: 2
            fail-fast: true
        jobs: 
            - first_job
            - third_job

jobs:
    first_job:
        type: # ...

    second_job:
        type: # ...

    third_job:
        type: # ...

Documentation

2.x Documentation (actual)
3.x Documentation (work in progress)

Contributing

Clone this wiki locally