Migration

Guides for moving onto GitHooks v3 from previous versions or competing tools. Pick the route that matches your starting point.

Coming from GitHooks v2

Single most-asked migration. v3 changes the configuration shape from Options / Tools to hooks / flows / jobs, adds execution modes (--fast, --fast-branch, --fast-dirty), per-job and flow-level budgets, job dependencies, branch-driven execution and per-entry admission rules.

Guide	When
From v2 to v3	You have a githooks.yml with Options: and Tools:. conf:migrate automates most of the conversion; the guide covers what changes manually.
v3.3 deprecations	You are already on v3.0–v3.2 and use camelCase job keys (executablePath, failFast…). v3.3 starts the deprecation cycle; v4.0 removes them. The guide is short — most projects can sed their way through it.

Coming from another tool

Guide	When
From GrumPHP	You currently run GrumPHP (grumphp.yml, YAML tasks).
From CaptainHook	You currently run CaptainHook (captainhook.json, PHP action classes).

If you are evaluating GitHooks against alternatives before committing, read Comparison first — it lays out the trade-offs without picking sides.

Fast path

If your project is on a recent v3 and you only want the latest features:

1. Read the Changelog for the version you are upgrading to.
2. Run githooks conf:check. It reports deprecations and unknown keys with did-you-mean suggestions.
3. Fix what conf:check reports.

That covers the vast majority of in-major upgrades. The dedicated guides above are only needed for cross-tool or cross-major moves.