Changelog¶

All notable changes to this project are documented here.

[3.1.0]¶

Local override (githooks.local.php): GitHooks looks for a githooks.local.php file alongside githooks.php. If found, its contents are merged over the main config using array_replace_recursive. Allows per-developer environment customization without modifying the shared config. Add githooks.local.php to .gitignore. See Docker & Local Override.
executable-prefix option: New option at global, flow, and job level. Prepends a command to all job executables (e.g. 'docker exec -i app'). Per-job override with '' or null to opt out. Enables Docker, Laravel Sail, and remote environments from a single config. See Options: executable-prefix.
Extra arguments via -- for job command: githooks job phpunit_all -- --filter=testFoo passes extra flags to the underlying tool. Enables dynamic execution from AI tools, scripts, or quick debugging without modifying configuration. See githooks job.
External documentation site: Full MkDocs Material site with getting started guide, configuration reference, CLI reference, tool docs, how-to guides, migration guides, and comparison page.

PHP minimum raised to 7.4. Dropped support for PHP 7.0-7.3.
SecurityChecker tool removed. Use a custom job with composer audit as replacement.
New configuration format: hooks/flows/jobs. Replaces the previous Options/Tools format. The old format still works but emits a deprecation warning.
tool command deprecated. Replaced by flow and job commands. Will be removed in v4.0.
YAML configuration deprecated. PHP format is now the primary format. YAML still works but emits a deprecation warning. Will be removed in v4.0.

Hooks: Map git events (pre-commit, pre-push, etc.) to flows and jobs. Uses core.hooksPath with a universal script instead of copying files to .git/hooks/.
Flows: Named groups of jobs with shared options (fail-fast, processes). Reusable across hooks and directly executable from CLI/CI.
Jobs: Individual QA tasks with declarative configuration. Each job declares a type (phpstan, phpcs, phpunit, custom, etc.) and its arguments.

githooks flow <name> — Run a flow by name. Supports --fail-fast, --processes=N, --exclude-jobs, --only-jobs, --dry-run, --format=json|junit, --fast, --fast-branch, --monitor.
githooks job <name> — Run a single job by name. Supports --dry-run, --format=json|junit, --fast, --fast-branch.
githooks hook:run <event> — Run all flows/jobs associated with a git hook event (called by the universal hook script).
githooks status — Show installed hooks, their sync state with config (synced/missing/orphan), and target flows/jobs.
githooks system:info — Show detected CPUs and current processes configuration with budget warning.
githooks conf:migrate — Migrate v2 configuration to v3 format with automatic backup.
githooks cache:clear — Clear cache files generated by QA tools. Accepts job names, flow names, or a mix.

githooks hook — Now uses core.hooksPath + .githooks/ directory instead of copying scripts to .git/hooks/. --legacy flag preserves old behavior (Git < 2.9).
githooks hook:clean — Default now removes .githooks/ + unsets core.hooksPath. --legacy flag removes individual hooks from .git/hooks/.
githooks conf:init — Now supports --legacy flag to generate v2 format.
githooks conf:check — Updated for v3: shows Options, Hooks, Flows, and Jobs tables with the full command each job will execute. Deep validation: verifies executables exist, paths are valid, and config files are accessible.

Custom: Replaces the v2 script tool. Supports script key (simple mode) and a new structured mode via executablePath + paths + otherArguments. Structured mode enables --fast acceleration identical to standard tools.

--format=json and --format=junit: Structured output for flow and job commands. JSON for machine-readable results; JUnit XML for CI test reporting.
fast-branch execution mode: New third mode alongside full and fast. Analyzes files that differ between the current branch and the main branch. Ideal for CI/CD. Non-accelerable jobs always run with full paths. Per-job accelerable key overrides the default. Deleted files are excluded automatically.
fast-branch-fallback option: Controls behavior when fast-branch cannot compute the diff (e.g. shallow clone). Values: full (default) or fast.
main-branch option: Configure the main branch name for fast-branch diff computation. Auto-detected if not specified.
Thread budget: processes now controls total CPU cores, not just parallel jobs. GitHooks distributes threads across jobs respecting each tool's capabilities (phpcs --parallel, parallel-lint -j, psalm --threads). PHPStan workers detected from .neon config.
--monitor flag: Shows peak estimated thread usage after flow execution, with warning if budget was exceeded.
Job argument validation: conf:check and flow/job commands validate job configuration keys and types at parse time.

--dry-run flag: Shows the exact shell command each job would execute without running anything. Works with all output formats — --format=json includes a command field per job.
--only-jobs flag: Inverse of --exclude-jobs for the flow command. Run only the specified jobs: githooks flow qa --only-jobs=phpstan_src,phpmd_src.
Deep validation in conf:check: Checks that executables exist, that configured paths are real directories, and that referenced config files are accessible.
Auto-detection of executablePath: When omitted, GitHooks looks for vendor/bin/{tool} before falling back to system PATH.

exclude-files: Excludes staged files matching glob patterns from triggering execution. Always prevails over only-files.
exclude-on: Excludes branches matching glob patterns. Always prevails over only-on.
Double-star (**) glob support: File patterns now support ** for recursive directory matching. src/**/*.php matches all PHP files under src/ at any depth.
hooks.command config key: Customize the command used in generated hook scripts (e.g. 'command' => 'php7.4 vendor/bin/githooks').