CaptainHook Documentation

The {$BRANCH_FILES} placeholder allows you to dynamically list files that have changed in your current branch.

Supported Hooks: This placeholder is only functional for the following actions:

• pre-push
• post-rewrite
• post-checkout
• post-merge

Note on pre-push: If you are pushing multiple refs at once, the placeholder will contain all changed files for all pushed refs.

Available Filters/Modifiers: You can pipe the placeholder through several filters to refine the list of files:

• |compare-to:<branch>: Compares the current branch against a specific branch (e.g., main). If not provided, it defaults to the branch's starting point from the reflog.
• |separated-by:<delimiter>: Defines the character used to separate the file list (e.g., a comma or space).
• |in-dir:<directory>: Limits the file list to a specific directory.
• |of-type:<extension>: Limits the file list to files with a specific extension (e.g., php).

# Compare current branch to main and separate by comma
{$BRANCH_FILES|compare-to:main|separated-by:,}

# List PHP files in the foo/bar directory
{$BRANCH_FILES|in-dir:foo/bar|of-type:php}

The {staged-files} placeholder allows you to dynamically resolve a list of files currently in the git index (staged files) during a hook execution. This is useful for running commands like linters or testers only on the files that are about to be committed.

You can customize the output of this placeholder using the following options:

• diff-filter: A string of Git diff filter characters (e.g., A for Added, M for Modified, C for Copied, D for Deleted) to restrict which staged files are returned. Defaults to ['A', 'C', 'M', 'R'].
• of-type: Restricts the files to a specific type (e.g., php, js).
• separated-by: A string used to separate the file paths in the resulting list. Defaults to a single space ( ).
• directory: (Implicitly used via FileList::filterByDirectory) Filters the list of files based on a directory path provided in the options.

<!-- Example usage in captainhook.json -->
{
    "actions": {
        "pre-commit": {
            "command": "vendor/bin/phpcs {staged-files}",
            "options": {
                "diff-filter": "M",
                "of-type": "php",
                "separated-by": " "
            }
        }
    }
}

The {$CHANGED_FILES} placeholder allows you to dynamically list files that have changed in the current commit or operation.

Supported Actions This placeholder is only available for the following hook types:

• pre-push (Note: if multiple refs are pushed, it contains all changed files for all refs)
• post-rewrite
• post-checkout
• post-merge

Filters and Formatting You can apply filters and separators to the placeholder using the pipe (|) syntax:

• Separators: Use separated-by:<char>, to change the delimiter between files (defaults to a space).
• Directory Filtering: Use in-dir:<path> to only include files within a specific directory.
• File Type Filtering: Use of-type:<extension> to only include files with a specific extension.

Example usage in a configuration file:

• {$CHANGED_FILES|separated-by:,}
• {$CHANGED_FILES|in-dir:foo/bar}
• {$CHANGED_FILES|of-type:php}

CaptainHook allows the use of placeholders within CLI command configurations to inject dynamic values. Placeholders follow a specific syntax using the pipe (|) character to separate the placeholder name from its options.

Syntax

{name}|option1:value1|option2:value2

• name: The identifier for the placeholder (case-insensitive).
• options: A list of key-value pairs separated by pipes, where each pair uses a colon (:) to separate the option name from its value (e.g., key:value).

Features

• Caching: You can control whether a placeholder's resolved value should be cached by using the cache option. By default, placeholders are cacheable. Setting cache:false disables caching for that specific placeholder.
• Option Parsing: Options are parsed using the pattern name:value. If a value is omitted (e.g., |option|), the value defaults to an empty string.

<!-- Example of placeholder syntax in a configuration file -->
{git_branch}|cache:false|prefix:feature/

CaptainHook allows you to use placeholders in your configuration to dynamically resolve values. These placeholders are processed during command execution and can refer to core configuration settings, custom settings, or plugin-specific options.

Supported Placeholder Prefixes

• Core Settings: Direct access to core configuration keys.
• custom>>: Accesses values defined in your custom settings.
• plugin>>: Accesses specific options from a plugin using the format plugin>>PluginClassName.optionKey.

Core Configuration Keys

You can use the following core keys as placeholders:

• bootstrap
• git-directory
• php-path

<!-- Example usage in a configuration file (conceptual) -->
{
    "actions": {
        "pre-commit": {
            "command": "php {{php-path}} {{custom>>my-script.path}}"
        }
    },
    "custom-settings": {
        "my-script": {
            "path": "scripts/test.php"
        }
    }
}