Skip to content

Running Your First Hook

Install the hooks

githooks hook

This command:

  1. Creates a .githooks/ directory with universal hook scripts for each event defined in your configuration.
  2. Runs git config core.hooksPath .githooks so Git uses these scripts.

Important

The .githooks/ directory should be committed to version control. The scripts are universal — they never need to be regenerated after config changes.

Test it

Make a commit and watch GitHooks run your configured QA tools:

git add .
git commit -m "test: verify githooks is working"

If all checks pass, the commit proceeds. If any check fails, the commit is blocked and you see the errors.

Run manually

You don't need to commit to run your QA tools. Use the CLI directly:

githooks flow qa                          # Run a flow (group of jobs)
githooks flow qa --fast                   # Only analyze staged 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 and AI integration
githooks job phpunit_all -- --filter=testFoo          # Pass extra args to the tool

Check hook status

githooks status

Shows which hooks are installed and whether they're synchronized with your configuration:

  • synced — installed and matches configuration.
  • missing — configured but not installed (run githooks hook to fix).
  • orphan — installed but not in configuration.

Automate installation

Add the hook installation to your composer.json so every team member gets hooks automatically:

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

PHP < 8.1

If you already have the ComposerUpdater script for PHP < 8.1, combine both: 

"scripts": {
    "post-update-cmd": [
        "Wtyd\\GitHooks\\Utils\\ComposerUpdater::phpOldVersions",
        "vendor/bin/githooks hook"
    ],
    "post-install-cmd": [
        "Wtyd\\GitHooks\\Utils\\ComposerUpdater::phpOldVersions",
        "vendor/bin/githooks hook"
    ]
}

Legacy mode (Git < 2.9)

If your environment doesn't support core.hooksPath, use legacy mode:

githooks hook --legacy

This copies hook scripts directly to .git/hooks/ instead.

What's next?

You have a working setup. From here you can: