wtyd/githooks

Manage git hooks in a simple and sophisticated way

v1.0.0 2020-12-03 19:10 UTC

This package is auto-updated.

Last update: 2021-01-21 18:11:53 UTC


README

68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6173742d636f6d6d69742f577479642f676974686f6f6b73 68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6973737565732f577479642f676974686f6f6b73 68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6963656e73652f577479642f676974686f6f6b73 PHP Versions Supported 68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f762f72656c656173652f577479642f676974686f6f6b73

badge.svg badge.svg badge.svg badge.svg

GitHooks helps you to manage the code validation tools in git hooks. For example, in precommit stage, you can:

  1. Validate that the code follows the project standards.
  2. Verify that the code has no language syntax errors.
  3. Look for errors in the code (unused variables, excessive cyclomatic complexity, etc.).

You can also create your own scripts and configure any git hook.

GitHooks centralizes the configuration of the code validation tools and makes it easy for the team to execute them in the same way every time. Further, it can be used together with javascript validation tools like typicode/husky if you have hybrid projects.

Requirements

  • PHP >= 7.1
  • The tools you need to check the code.
  • Or your owns scripts for the hooks.

Install

  1. GitHooks must be installed like dev requirement with composer. Currently, it does not have .phar packaging.

    composer require --dev wtyd/githooks
  2. Install all needed supported tools. The installation method for the tools can be:

    • Like global dependency with composer: composer global require squizlabs/php_codesniffer
    • Like dev requirement in the project: composer require --dev sebastian/phpcpd
    • Like .phar on the root of the project or with global access.
  3. Initialize GitHooks with vendor/bin/githooks conf:init. This command creates the configuration file in the root paths (githooks.yml).

  4. Run vendor/bin/githooks hook. It Copies the script for launch GitHooks on the precommit event in .git/hooks directory. You can, also run vendor/bin/githooks hook otherHook MyScriptFile.php for set any hook with a custom script.

  5. Set the configuration file.

Usage

When you commit, all the configured code check tools are automatically launched. If your code pass all checks, GitHooks allows you to commit. If not, you have to fix the code and try again:

Imagen todo OK

Imagen con KO

We can also launch all the tools one by one by command line in the way they are setted for the project:

Imagen de una herramienta

Supported Tools

At this moment, the supported tools are:

But you can set your own script on any git hook.

Set the Configuration File

The githooks.yml file is splitted on three parts:

Options

Actually the only option is execution. This 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.
  • smart: This option tries to save execution time when running the application. For this, it may not execute any of the configured tools if all the commit files do not belong to any of the directories against which the tool is launched or are files that are in excluded or ignored directories. For example: in the above case of phpcs, phpcs will not be executed. Another case, if you modify a test and phpmd has the tests folder excluded, phpmd won't run either.
    • The tools this option affects are: phpcs, phpmd, phpcpd, and parallel-lint. That is, they may not be executed even if they are configured.
    • The tools that are NOT affected by this strategy are: phpstan (you can only mark exclusions in its configuration file) and security-check. These tools will run as long as they are configured even if the smart option is active.
  • fast: this option runs the tools only 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.

Tools

It is an array with the name of the tools that GitHooks will run. The name of the tools is their executable. If you want all the tools to be executed, the Tools key will be as follows:

Tools:
    - phpstan
    - check-security
    - parallel-lint
    - phpcs
    - phpmd
    - phpcpd

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

Setting Tools

In next step you must configure the tools with the same name as in the Tools key. For example, for set phpcs:

phpcs:
    paths: [src, tests]
    ignore: [vendor]
    standard: 'PSR12'

All the available options are:

Option Description Examples
phpstan
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'
paths Array. Paths or files against the tool will be executed ['./src'], ['./src', './app/MiFile.php']
level Integer. Default 0, max 8. 0, 1, 5, 8
parallel-lint
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']
phpcs
paths Array. Paths or files against the tool will be executed [src], [src, './app/MiFile.php']
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
phpmd
paths Array. Paths or files against the tool will be executed ['./src'], ['./src', './app/MiFile.php']
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']
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']

These are the options supported by GitHooks. Obviously, each tool has many other options. More precise configuration is possible with each tool configuration file. The check-security tool has no configuration.

Many of the options are optional as long as the tool has a properly established configuration file. The conf:init command copies a githooks.yml file template to the root of the project with all the options commented of each the tool. To make sure that when you finish configuring it, all the options are valid, you can launch the command conf:check:

conf:check

Contributing

Contributions from others would be very much appreciated! Send pull request/issue. Check all steps for do that at Wiki section for Contributing. Thanks!

License

The MIT License (MIT). Please see License File for more information.