README

1. Wtyd/GitHooks

GitHooks is a standalone CLI tool (.phar) for managing git hooks and running QA tools in PHP projects. Built with Laravel Zero.

Why GitHooks?

• Standalone binary — distributed as .phar, so its dependencies don't interfere with your project.
• Managed with Composer — no need for Phive or other tools.
• Unified configuration — one file (githooks.php) configures all QA tools, hooks, and execution options.
• Hooks, flows, jobs — map git events to groups of QA tasks with parallel execution, fail-fast, and conditional execution.
• Language agnostic — the custom job type can run any command (eslint, prettier, composer audit, etc.), so GitHooks manages both backend and frontend QA from a single configuration.

2. Requirements

• PHP >= 7.4
• The QA tools you want to run (phpstan, phpcs, phpmd, etc.)

3. Install

1. Install GitHooks as a dev dependency:

composer require --dev wtyd/githooks

Note: for PHP < 8.1 you must add the following events to the scripts section in your composer.json:

"scripts": {
    "post-update-cmd": "Wtyd\\GitHooks\\Utils\\ComposerUpdater::phpOldVersions",
    "post-install-cmd": "Wtyd\\GitHooks\\Utils\\ComposerUpdater::phpOldVersions"
}

Then run composer update wtyd/githooks.

2. Initialize the configuration file:

githooks conf:init

In interactive mode, GitHooks detects QA tools in vendor/bin/ and generates a tailored githooks.php. You can also use --no-interaction to copy a template.

3. Install the git hooks:

githooks hook

This creates a .githooks/ directory with universal hook scripts and configures git config core.hooksPath .githooks. The .githooks/ directory should be committed to version control.

To automate hook installation, add it to your composer.json:

"scripts": {
    "post-update-cmd": [
        "vendor/bin/githooks hook"
    ],
    "post-install-cmd": [
        "vendor/bin/githooks hook"
    ]
}

4. Usage

When you commit, all configured QA tools run automatically. If all checks pass, the commit proceeds. If not, you fix the code and try again.

All checks passed:

  parallel_lint - OK. Time: 150ms
  phpcs_src - OK. Time: 890ms
  phpstan_src - OK. Time: 2.34s
  phpmd_src - OK. Time: 1.23s

Results: 4/4 passed in 3.45s

Some checks failed:

  parallel_lint - OK. Time: 150ms
  phpcs_src - OK. Time: 890ms
  phpstan_src - KO. Time: 2.34s
  phpmd_src - OK. Time: 1.23s

  phpstan_src:
    /src/Foo.php:12  Access to undefined property $bar
    /src/Foo.php:34  Method doSomething() has no return type

Results: 3/4 passed in 3.45s

Running manually

githooks flow qa                                       # Run a flow (group of jobs)
githooks flow qa --fast                                # Only staged files (accelerable jobs)
githooks flow qa --fast-branch                         # Only files changed vs the base branch
githooks flow qa --fast-dirty                          # Unified working tree (ideal for AI agents)
githooks flow qa --fast-dirty --format=json --no-reports  # AI-agent friendly: clean JSON, no side-effect files
githooks flow qa --only-jobs=phpstan_src               # Run specific jobs from a flow
githooks flow qa --dry-run                             # Show commands without executing
githooks job phpstan_src                               # Run a single job
githooks job phpstan_src --format=json                 # JSON output for CI integration

5. Configuration

GitHooks uses a PHP configuration file (githooks.php) with three sections: hooks, flows, and jobs.

<?php
return [
    // Git hooks: map git events to flows/jobs
    'hooks' => [
        'command'    => 'php7.4 vendor/bin/githooks', // optional: customize the hook script command
        'pre-commit' => ['qa'],
        'pre-push'   => [
            ['flow' => 'full', 'only-on' => ['main', 'develop']], // only on these branches
        ],
    ],

    // Flows: named groups of jobs with shared execution options
    'flows' => [
        'options' => ['fail-fast' => false, 'processes' => 2], // global defaults
        'qa'   => ['jobs' => ['phpcbf_src', 'phpcs_src', 'phpmd_src', 'parallel_lint']],
        'full' => ['jobs' => ['phpstan_src', 'phpunit_all']],

        // CI flow that picks its mode per branch and declares intra-flow dependencies
        'ci' => [
            'on' => [
                'master' => ['execution' => 'full'],          // full on protected branches
                '*'      => ['execution' => 'fast-branch'],   // diff vs base everywhere else
            ],
            'jobs' => [
                'yarn_install',                                                  // installs node_modules
                ['job' => 'eslint_src',  'needs' => ['yarn_install']],            // waits for install
                ['job' => 'phpunit_all', 'only-files' => ['src/**', 'tests/**']], // admission gate
            ],
        ],
    ],

    // Jobs: individual QA tasks with declarative configuration
    'jobs' => [
        'phpcs_src' => [
            'type'     => 'phpcs',
            'paths'    => ['src'],
            'standard' => 'PSR12',
            'ignore'   => ['vendor'],
            // executable-path omitted: auto-detects vendor/bin/phpcs, then system PATH
        ],
        'phpcbf_src' => [
            'extends' => 'phpcs_src', // inherits paths, standard, ignore from phpcs
            'type'    => 'phpcbf',    // overrides type
        ],
        'phpmd_src' => [
            'type'            => 'phpmd',
            'executable-path' => 'tools/phpmd', // explicit path when not in vendor/bin
            'paths'           => ['src'],
            'rules'           => 'cleancode,codesize,naming,unusedcode',
        ],
        'parallel_lint' => [
            'type'    => 'parallel-lint',
            'paths'   => ['src'],
            'exclude' => ['vendor'],
        ],
        'phpstan_src' => [
            'type'  => 'phpstan',
            'level' => 8,
            'paths' => ['src'],
        ],
        'phpunit_all' => [
            'type'   => 'phpunit',
            'config' => 'phpunit.xml',
        ],
        'composer_audit' => [
            'type'   => 'custom', // run any command
            'script' => 'composer audit',
        ],
        'yarn_install' => [
            'type'   => 'script', // one-liner; no path filtering
            'script' => 'yarn install --frozen-lockfile',
        ],
        'eslint_src' => [
            'type'            => 'custom',
            'executable-path' => 'npx eslint',    // structured mode: executable + paths
            'paths'           => ['resources/js'],
            'other-arguments' => '--fix',
            'accelerable'     => true,            // opt-in: filters paths to staged files with --fast
        ],
    ],
];

Key concepts

• Hooks map git events (pre-commit, pre-push, etc.) to flows and jobs. Supports conditional execution by branch (only-on / exclude-on) and staged file patterns (only-files / exclude-files).
• Flows are named groups of jobs with shared options (fail-fast, processes, time-budget, memory-budget, reports). Reusable across hooks and directly executable from CLI. A flow can declare on => [branch_pattern => attrs] to pick its execution mode per branch (e.g. full on master, fast-branch elsewhere). Each entry in jobs accepts the plain job name or an object {job, needs?, only-files?, exclude-files?} to declare intra-flow dependencies and per-entry admission gates. Meta-flows (flows.<X>.flows) compose other flows in a single run.
• Jobs are individual QA tasks. Each declares a type and its arguments. Jobs can inherit from other jobs with extends. When executable-path is omitted, GitHooks auto-detects the binary in vendor/bin/. Per-job thresholds (warn-after, fail-after, memory, cores) cap regressions.
• Execution modes: full (default), --fast (only staged files), --fast-branch (only files changed vs base branch), --fast-dirty (unified working tree: dirty vs HEAD ∪ untracked — ideal for AI agentic hooks), --files / --files-from (explicit list).

See the documentation site for the full configuration reference.

6. Supported Tools

Two ways to run non-PHP tools:

• script — minimal, one-liner command for tools that don't take paths (composer audit, npm audit, etc.).
• custom — path-aware execution. Two modes: pass the full command in script, or declare executable-path + paths + optional other-arguments. Set accelerable: true to filter paths down to staged / branch-changed files when running with --fast / --fast-branch.

7. Commands

Common flags for flow / flows / job

See the documentation site for the full command reference.

8. Documentation

Full documentation is available at wtyd.github.io/githooks, including:

• Getting Started — installation, first config, first hook.
• Configuration Reference — hooks, flows, jobs, options.
• Tools Reference — all keywords for each QA tool.
• CLI Reference — every command with options and examples.
• How-To Guides — parallel execution, CI/CD, frontend tools, etc.
• Migration — from v2, GrumPHP, or CaptainHook.
• Comparison — GitHooks vs GrumPHP vs CaptainHook.
• Changelog — what's new in each version.

9. Contributing

Contributions are welcome! Send a pull request or open an issue. See the Contributing guide.

10. License

The MIT License (MIT). Please see License File for more information.