githooks

KO | EN

gitlite — search

#javascript #python #typescript #go #golang #android #machine-learning #docker #cli #kubernetes #vue #mcp #openai #open-source

(★ 9)

Manage git hooks in a simple and sophisticated way.

githooks Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# 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:
```bash
composer require --dev wtyd/githooks
```

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

```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:
```bash
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:
```bash
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`:

```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

```bash
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
<?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](https://wtyd.github.io/githooks/) for the full configuration reference.

# 6. Supported Tools

| Tool | Type | Description |
|---|---|---|
| [PHP CodeSniffer](https://github.com/PHPCSStandards/PHP_CodeSniffer) | `phpcs` / `phpcbf` | Code style checking and auto-fixing |
| [PHPStan](https://github.com/phpstan/phpstan) | `phpstan` | Static analysis |
| [Psalm](https://psalm.dev/) | `psalm` | Static analysis |
| [PHP Mess Detector](https://phpmd.org/) | `phpmd` | Code quality rules |
| [Parallel-lint](https://github.com/php-parallel-lint/PHP-Parallel-Lint) | `parallel-lint` | Syntax checking |
| [PHPUnit](https://phpunit.de/) | `phpunit` | Unit testing |
| [Paratest](https://github.com/paratestphp/paratest) | `paratest` | Parallel PHPUnit driver |
| [Pest](https://pestphp.com/) | `pest` | PHPUnit-based testing framework, Laravel's default runner (`vendor/bin/pest` or `php artisan test`) |
| [PHP CS Fixer](https://cs.symfony.com/) | `php-cs-fixer` | Code style auto-fixing |
| [Rector](https://getrector.com/) | `rector` | Automated code refactoring |
| [PHP Copy Paste Detector](https://github.com/sebastianbergmann/phpcpd) | `phpcpd` | Duplicate code detection |
| Inline command | `script` | Run one executable with fixed arguments (`executable-path` + `other-arguments`). No path filtering. |
| Any tool | `custom` | Run any binary with `script` (one-liner) or `executable-path` + `paths` (+ `accelerable: true` to opt into `--fast` / `--fast-branch` filtering) |
| Commit message | `commit-msg` | Validate the commit-message subject (declarative rules + `conventional-commits` preset), wired to Git's `commit-msg` hook. Runs inline, no shell. |

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

| Command | Description |
|---|---|
| `githooks flow <name>` | Run a single flow. |
| `githooks flows <name1> <name2>…` | Run multiple flows in a combined plan: ad-hoc list, declarative meta-flow, or mixed. Jobs deduped by first occurrence. |
| `githooks job <name>` | Run a single job. Pass extra args to the underlying tool with `--`: `githooks job phpunit -- --filter=MyTest`. |
| `githooks hook` | Install git hooks via `core.hooksPath`. |
| `githooks hook:clean` | Remove installed hooks. |
| `githooks status` | Show hook installation status. |
| `githooks cache:clear [jobs…]` | Clear QA tool cache files. Accepts job names, flow names, or no argument (clear all). |
| `githooks conf:init` | Generate configuration file (interactive or template). |
| `githooks conf:check` | Validate configuration with deep checks (paths, executables, configs, deprecations, did-you-mean for typos). |
| `githooks conf:migrate` | Migrate v2 config to v3 format. |
| `githooks system:info` | Show CPU detection (cgroup-aware) and process configuration. |
| `githooks profile <flow>` | Chart a metric (`time`, `peak-memory`, `peak-cores`) across the flow's run history as a sparkline with min/p50/p95/max and a trend. Requires recorded runs (see `--save-history` / `history-size`). |
| `githooks profile:list <flow>` | List the runs persisted under `.githooks/history/` for a flow. |

### Common flags for `flow` / `flows` / `job`

| Flag | Purpose |
|---|---|
| `--mode=full\|fast\|fast-branch\|fast-dirty` / `--fast` / `--fast-branch` / `--fast-dirty` | Select execution mode. `fast` filters to staged files, `fast-branch` to files changed vs base branch, `fast-dirty` to the unified working tree (dirty vs `HEAD` ∪ untracked). |
| `--branch=X` *(`flow` only)* | Force branch name used to resolve `flows.<X>.on => [branch_pattern => …]`. Overrides CI env vars and `git rev-parse HEAD`. In `flows`/`job`, branch resolution falls back to `$GITHOOKS_BRANCH` / CI env / git. |
| `--files=a,b,c` / `--files-from=PATH` / `--exclude-pattern=glob` | Run against an explicit list of files (CSV, manifest, or with exclusion patterns). |
| `--processes=N`, `--fail-fast`, `--only-jobs=a,b`, `--exclude-jobs=a,b`, `--dry-run` | Control parallelism, fail-fast behaviour, and job selection. |
| `--format=text\|json\|junit\|sarif\|codeclimate` | Output format on stdout. JSON v2 schema is stable. |
| `--report-json=PATH`, `--report-junit=PATH`, `--report-sarif=PATH`, `--report-codeclimate=PATH` | Write structured reports to files (one or many at once). `--no-reports` skips the config-declared reports. |
| `--output=PATH` | Write the `--format=…` payload to a file instead of stdout. |
| `--show-progress` | Force progress to stderr even with a structured `--format` (CI dashboards). |
| `--stats` | Print a 5-column table (Job / Status / Time / Peak Cores / Peak Memory) plus temporal attribution at the end of the flow. Also exposes `stats` block in JSON v2. |
| `--save-history` *(`flow` / `flows`)* | Persist this run under `.githooks/history/` so `profile` can chart its trend (opt-in; never on `--dry-run`). |
| `--warn-after=N`, `--fail-after=N`, `--no-time-budget` | Override flow time-budget thresholds (seconds). |
| `--memory-warn-above=MB`, `--memory-fail-above=MB`, `--no-memory-budget`, `--allocator=fifo\|greedy` | Override memory-budget thresholds and 2D allocator strategy. |

See the [documentation site](https://wtyd.github.io/githooks/) for the full command reference.

# 8. Documentation

Full documentation is available at **[wtyd.github.io/githooks](https://wtyd.github.io/githooks/)**, including:

- [Getting Started](https://wtyd.github.io/githooks/getting-started/installation/) — installation, first config, first hook.
- [Configuration Reference](https://wtyd.github.io/githooks/configuration/) — hooks, flows, jobs, options.
- [Tools Reference](https://wtyd.github.io/githooks/tools/) — all keywords for each QA tool.
- [CLI Reference](https://wtyd.github.io/githooks/cli/) — every command with options and examples.
- [How-To Guides](https://wtyd.github.io/githooks/how-to/) — parallel execution, CI/CD, frontend tools, etc.
- [Migration](https://wtyd.github.io/githooks/migration/v2-to-v3/) — from v2, GrumPHP, or CaptainHook.
- [Comparison](https://wtyd.github.io/githooks/comparison/) — GitHooks vs GrumPHP vs CaptainHook.
- [Changelog](https://wtyd.github.io/githooks/changelog/) — what's new in each version.

# 9. Contributing
Contributions are welcome! Send a [pull request](https://github.com/Wtyd/githooks/pulls) or open an [issue](https://github.com/Wtyd/githooks/issues). See the [Contributing](https://github.com/Wtyd/githooks/wiki/Contributing) guide.

# 10. License
The MIT License (MIT). Please see [License File](/LICENSE) for more information.

githooks

githooks Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

githooks

githooks Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README