Using the PHAR release

The easiest way to install CaptainHook is by using the PHAR file and install it using PHIVE. You can also download the PHAR manually from the CaptainHook release page.

$ phive install captainhook

Install using Composer

Installing CaptainHook via composer is also supported. You can choose between installing the PHAR or the source code with all its dependencies.

$ composer require --dev captainhook/captainhook-phar
$ composer require --dev captainhook/captainhook

This will install the `captainhook` executable usually located under vendor/bin/captainhook.


The next step is to create a configuration file, to define the actions you want to execute for each git hook. You can either use a sample configuration from the documentation or create one by running the following command. Be aware, that if you changed your composer bin directory or use the PHAR, you must adjust the path.

$ vendor/bin/captainhook configure

While executing this, CaptainHook will ask you a series of questions to create a valid configuration file for you.

After creating the configuration file, there is only one step left to finish the installation. You must activate the hooks in your local git repository. To do so, just run the following command.

$ vendor/bin/captainhook install

Executing this will create the hook script located in your .git/hooks directory, for each hook you choose to install while running the command. So now every time git triggers a hook, CaptainHook gets executed.

AYE! Ye have successfully installed CaptainHook to handle yer git hooks. Want to know how to set sail? Have a closer look at thee configuration file to set up yer git hooks.

There are more options to further integrate CaptainHook with Composer. For details check the Composer integration page.

Using Docker

If you don't have PHP installed locally, or you have installed a different version, you can use Docker to execute CaptainHook. To do so you must install the hooks a bit differently.

$ vendor/bin/captainhook install --run-mode=docker --run-exec="docker exec -i CONTAINER_NAME"

You can choose your preferred docker command e.g.:

If you are using the composer plugin or just don't want to provide the settings via cli option you can configure the settings in the "config" section of your captainhook.json.

  "config": {
    "run": {
      "mode": "docker",
      "exec": "docker exec -i CONTAINER_NAME"
  "pre-commit": {

Another optimization you could to is to only install hooks that are enabled in your configuration. This way git will not trigger the creation of a Docker container just to output that the hook is disabled. To make sure you only install enabled hooks use the corresponding flag during installation.

$ vendor/bin/captainhook install --only-enabled --run-mode=docker --run-exec="docker exec -i CONTAINER_NAME"

A word of warning

Don't ye forget it is still possible to commit without invoking thee hooks. Make sure ye run appropriate backend-sanity checks on yer code, so yer hearties don't break anything AYE!!!