Configuration

If you look at a captainhook.json configuration, it consists of a config block for each hook.

{
  'commit-msg': {
    // a hook config block
  },
  'pre-commit': {
    // another hook config block
  },
  // ...
}

Hook Config

Each hook configuration consists of two things an on/off switch and a list of actions to execute.

'commit-msg': {
  'enabled': true,
  'actions': []
}

By setting enabled to false, CaptainHook will not execute the configured actions even if the hook is triggered by git.

Actions

CLI commands

Actions can be two things, firstly you can run any cli command, as long as it uses exit codes to notify the caller about its success. If you, for example, run PHPUnit and a test fails, it will exit with status code 1, so CaptainHook knows that it should stop the currently running git command with an error.

{
  'pre-commit': {
    'enabled': true,
    'actions': [
      {
        'action': 'phpunit.phar --configuration=phpunit.git.xml'
      }
    ]
  }
}

Using the example above in a pre-commit hook will prevent you from committing code that breaks any unit test.

PHP scripts

Secondly you can execute any PHP class implementing an interfaces defined by CaptainHook. The interface you have to implement is \SebastianFeldmann\CaptainHook\Hook\Action. CaptainHook comes with some built-in, basic validation classes. So let's have a look at how to configure those.

{
  'commit-msg': {
    'enabled': true,
    'actions': [
      {
        'action': '\SebastianFeldmann\CaptainHook\Hook\Message\Action\Regex',
        'options': {
          'regex': '#.*#'
        }
      }
    ]
  }
}

With this configuration you can validate your commit messages against a regular expression. If your commit message doesn't match your regular expression your commit fails.

Here's a list of all built-in actions

Commit-Message
Pre-Commit

You can easily build your own action classes. Have a look on how to extend CaptainHook.