wtyd/githooks

Manage git hooks in a simple and sophisticated way.

v2.5.0 2023-04-17 18:47 UTC

Requires

• php: >=7.1

Requires (Dev)

• fakerphp/faker: ^1.19
• intonate/tinker-zero: 1.*
• laravel-zero/framework: ^5.0 | ^6.0 | ^7.0 | 8.* | 9.*
• laravel-zero/phar-updater: ^1.0.6
• mikey179/vfsstream: ^1.6
• mockery/mockery: ^1.3
• php-mock/php-mock: ^2.2
• php-parallel-lint/php-parallel-lint: ^1.2
• phpmd/phpmd: ^2.9
• phpstan/phpstan: ^1.4
• phpunit/php-code-coverage: ^6.0 | ^7.0 | ^8.0 | ^9.0 | ^10.0
• phpunit/phpunit: ^7.0 | ^8.0 | ^9.0
• squizlabs/php_codesniffer: ^3.5
• symfony/yaml: ^3.0 | ^4.0 | ^5.0 | 6.*

MIT

• Jorge Lilao
• Pablo Lilao

• cli
• git
• console
• hooks
• qa
• commit
• githooks
• pre-commit
• precommit

README

1. Wtyd/GitHooks

Are many other tools and composer plugins for manage git hooks. But GitHooks offers:

• Standalone app. GitHooks is a binary (.phar) so its dependencies don't interfere with your application's dependencies.
• Is managed with Composer. You don't need other tools like Phive or others.
• Crentralizes all QA tools configuration (all of supported tools at least).
• It abstracts developers away from how QA tools have to be executed by using only the githooks tool name-of-the-tool command.
• You can also create your own scripts and configure any git hook.

Further, it can be used together with javascript validation tools like typicode/husky if you have hybrid projects.

2. Requirements

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

3. Install

1. GitHooks must be installed like dev requirement with composer:

composer require --dev wtyd/githooks

Note: for php < 8.1 you must add the next post-update-cmd event to the scripts section in your composer.json:

"scripts": {
    "post-update-cmd": [
      "Wtyd\\GitHooks\\Utils\\ComposerUpdater::phpOldVersions"
    ]
}

Then run composer update wtyd/githooks.

Until version 2.3.0 the method used was php72orMinorUpdate but it has been deprecated and will be removed from version 3.0.0

It is also convenient to add it to the post-install-cm event so that the rest of the project developers do not have problems with the build

"scripts": {
    "post-update-cmd": "Wtyd\\GitHooks\\Utils\\ComposerUpdater::phpOldVersions",
    "post-install-cmd": "Wtyd\\GitHooks\\Utils\\ComposerUpdater::phpOldVersions"
}

2. Install all needed supported tools. How you install the tools doesn't matter.

3. Initialize GitHooks with githooks conf:init. This command creates the configuration file in the root path (githooks.yml).

4. Run githooks hook. It Copies the script for launch GitHooks on the pre-commit event in .git/hooks directory. You can, also run githooks hook otherHook MyScriptFile.php for set any hook with a custom script. See the wiki for more information.

To ensure that it is configured automatically, we can configure the command in the post-update-cmd and post-install-cmd events of the composer.json file (scripts section):

"scripts": {
    "post-update-cmd": [
    "vendor/bin/githooks hook" // or "vendor/bin/githooks hook pre-commit MyScriptFile.php"
    ],
    "post-install-cmd": [
    "vendor/bin/githooks hook"
    ]
}

5. Set the configuration file.

4. 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:

You can also run GitHooks whenever you want. All tools at same time or one by one:

githooks tool all # Run all tools
githooks tool phpcs # Run only phpcs

5. Supported Tools

At this moment, the supported tools are:

• Php CodeSniffer (phpcs and phpcbf)
• Php Copy Paste Detector
• Php Mess Detector
• Parallel-lint
• Php Stan
• Local PHP Security Checker

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

6. Set the Configuration File

The githooks.yml file is splitted on three parts:

6.1. Options

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

6.1.2. Processes

Run multiple tools in multiple processes at same time (tool all command). The default number of processes is 1.

6.2. 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
    - security-checker
    - parallel-lint
    - phpcs
    - phpcbf
    - phpmd
    - phpcpd

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

6.3. 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:
    executablePath: vendor/bin/phpcs
    paths: [src, tests]
    ignore: [vendor]
    standard: 'PSR12'

All the available options are in the wiki.

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

8. License

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