Actions & Conditions

Here's a list of all CaptainHook's built-in Actions and Conditions.

Actions

Commit-Message validation

Enforce Chris Beams commit message rules

Make sure your commit message complies to the following rules. 

{
  "action": "\CaptainHook\App\Hook\Message\Action\Beams",
  "options": []
}

Commit message regex validation

Use a regex to validate your commit messages. 

{
  "action": "\CaptainHook\App\Hook\Message\Action\Regex",
  "options": {
    "regex": "#.*#i",
    "error": "No match for: %s",
    "success": "Found match: %s"
  }
}
Options "error" and "success" are optional.

Define rules for your commit messages

Use CaptainHooks built in rules or write your own ones. 

{
  "action": "\CaptainHook\App\Hook\Message\Action\Rules",
  "options": [
    "\CaptainHook\App\Hook\Message\Rule\MsgNotEmpty"
  ]
}

Write invalid commit message to file

Writes the invalid commit message to a file. This way it can be loaded for the next commit attempt, and you don't have to type the whole message again. Instead, you can just fix the errors and proceed. 

{
  "action": "\CaptainHook\App\Hook\Message\Action\CacheOnFail",
  "options": {
    "file": ".git/CH_MSG.temp"
  }
}

Commit-Message preparation

Be aware that prepare-commit-msg hooks should support two scenarios:
  1. Commit without providing a message
    Then the editor will load with your prepared commit message to edit.
  2. Commit with providing a message
    This way the commit message will be whatever you prepare. So you have to use the provided message and combine it with your "preparation" otherwise you will just overwrite the message.

Inject issue key into your commit message

Extracts an issue key from the current branch name and appends or prepends it to your commit messages subject or body. If the commit message already contains the key nothing is added. If you set the force option to true it will fail if no issue key can be extracted. 

{
  "action": "\CaptainHook\App\Hook\Message\Action\InjectIssueKeyFromBranch",
  "options": {
    "regex": "#([A-Z]+\\-[0-9]+)#i",
    "into": "body",
    "mode": "append",
    "prefix": "\\n\\nIssue: ",
    "force": false
  }
}

Load commit message from file

Load a commit message from a file for example if you wrote an invalid commit message to a file in a previous commit attempt. 

{
  "action": "\CaptainHook\App\Hook\Message\Action\LoadFromFile",
  "options": {
    "file": ".git/CH_MSG.temp"
  }
}

Pre-Commit / Pre-Push

Composer lock file check

Make sure your composer.lock file is up to date. 

{
  "action": "\CaptainHook\App\Hook\Composer\Action\CheckLockFile",
  "options": []
}

Lint all changed PHP files

Make sure your PHP code doesn't contain any syntax errors. 

{
  "action": "\CaptainHook\App\Hook\PHP\Action\Linting",
  "options": []
}

Monitor your unit test code coverage

Make sure you code coverage doesn't decrease beyond a given percent value. 

{
  "action": "\CaptainHook\App\Hook\PHP\Action\TestCoverage",
  "options": {
    "minCoverage": 90,
    "cloverXml": "build/logs/clover.xml"
  }
}

Check if files are too big

Make sure you do not commit files that are bigger than a configured size limit.
Use 'B', 'K' or 'M' as size indication. 

{
  "action": "\CaptainHook\App\Hook\File\Action\MaxSize",
  "options": {
    "maxSize": "5M"
  }
}

Check if a file is empty or does not exist

Make sure you do not commit if there is any file of a configured list that is not empty. The following configuration makes sure you will not commit log files with contents to the repository. 

{
  "action": "\CaptainHook\App\Hook\File\Action\IsEmpty",
  "options": {
    "files": [
      ".env",
      "logs/event.log",
      "logs/app/*.log"
    ]
  }
}

Check if a file is not empty

Make sure you do not commit empty files to the repository. With this configuration you can make sure that README files are not committed without any contents. 

{
  "action": "\CaptainHook\App\Hook\File\Action\IsNotEmpty",
  "options": {
    "files": [
      "README.md",
      "src/Modules/**/README.md"
    ]
  }
}

Check if a file does not contain certain text

Make sure you do not commit specific contents to a list of file types. 

{
  "action": "\CaptainHook\App\Hook\File\Action\DoesNotContainRegex",
  "options": {
    "regex": "#print_r|var_dump#i"
    "regexName": "debug output"
    "fileExtensions": [
      "inc",
      "php"
    ]
  }
}

Ensure a file exists

Make sure you are only allowed to push if configured files exist in the repository. 

{
  "action": "\CaptainHook\App\Hook\File\Action\Exists",
  "options": {
    "files": [
      "tests/**/*Tests.php",
      "README.md"
    ]
  }
}

Enforce branch naming rules

Make sure branch names match a configured regex. 

{
  "action": "\CaptainHook\App\Hook\Branch\Action\EnsureNaming",
  "options": {
    "regex": "#master|integration|feature/[a-z]+-[0-9]+#"
  }
}

Block pushing of !fixup or !squash commits

Preparing !fixup or !squash commits for smooth rebasing is very handy. But you may not want to push those commits to the main branch. If you don't provide any protected branches push fixup and squash commits is generally prohibited. 

{
  "action": "\CaptainHook\App\Hook\Branch\Action\BlockFixupAndSquashCommits",
  "options": {
    "protectedBranches": ["main", "master"]
  }
}

Post-Merge, Post-Rewrite, Post-Checkout

Display notifications if you merge or checkout commits with notifications

Trigger notifications with git commit messages. Use git-notify: in your commit message to display notifications after merge, rebase or checkout.
Inspired by: git-notify from Jani Eväkallio 

Update dev tooling

git-notify: WARNING
Please update your dev tooling

{
  "action": "\CaptainHook\App\Hook\Notify\Action\Notify",
  "options": {
    "prefix": "git-notify:"
  }
}

Conditions

All files changed

Execute an action only if all the configured files changed. 

{
    "action": "my-action",
    "options": [],
    "conditions": [
        {
            "exec": "\\CaptainHook\\App\\Hook\\Condition\\FileChanged\\All",
            "args": [
                [
                    "trigger-file-1",
                    "trigger-file-2"
                ]
            ]
        }
    ]
}

Any file changed

Execute an action only if any of the configured files changed. 

{
    "action": "composer install",
    "options": [],
    "conditions": [
        {
            "exec": "\\CaptainHook\\App\\Hook\\Condition\\FileChanged\\Any",
            "args": [
                [
                    "composer.json",
                    "composer.lock"
                ]
            ]
        }
    ]
}