CaptainHook is an easy to use and very flexible git hook library for php developers. It enables you to configure your git hook actions in a simple json file.

You can use CaptainHook to validate or prepare your commit messages, ensure code quality or run unit tests before you commit or push changes to git. You can automatically clear local caches or install the latest composer dependencies after pulling the latest changes.

CaptainHook makes it easy to share hooks within your team and even can make sure that everybody in your team activates the hooks locally.

You can run cli commands, use some built in validators, or write your own PHP classes that get executed by CaptainHook. For more information have a look at the documentation.

The preferred method to install CaptainHook is to install the PHAR file. You can do so by using Phive, use the PHAR Composer package, or download the PHAR from the GitHub release page.

phive install captainhook

Or use Composer to install it.

composer require --dev captainhook/captainhook-phar

If you want to get the source code with all its dependencies you can use:

composer require --dev captainhook/captainhook

After installing CaptainHook you can use the captainhook executable to create a configuration.

vendor/bin/captainhook configure

After creating the captainhook.json configuration file you have to activate the hooks by installing them to your local .git directory. To do so just run the following CaptainHook command.

vendor/bin/captainhook install

Have a look at this short installation video.

One of the goals of CaptainHook is to make it easy for a team to use the same git hooks. If you want to make sure everybody actually installs the hooks you can use the small Composer plugin hook-installer. It runs the captainhook install command everytime you run a Composer command.

composer require --dev captainhook/hook-installer

Off course teammates can still commit without executing the hooks, that's why you should run appropriate checks on the backend as well. But at least this way nobody can forget to install them "by accident".

Here's an example captainhook.json configuration file.

{
  "commit-msg": {
    "actions": [
      {
        "action": "\\CaptainHook\\App\\Hook\\Message\\Action\\Beams"
      }
    ]
  },
  "pre-commit": {
    "actions": [
      {
        "action": "phpunit"
      },
      {
        "action": "phpcs --standard=psr12 src"
      }
    ]
  }
}

The full documentation can be found at php.captainhook.info.

So you'd like to contribute to the CaptainHook project? Excellent! Thank you very much. I can absolutely use your help.

Have a look at the contribution guidelines.