githooks flow¶

Run a flow by name. A flow executes its configured jobs with the flow's options.

Synopsis¶

githooks flow <name> [options]

Options¶

Most flags below are CLI overrides for keys declared under flows.options or per-flow options:. The table here describes the CLI form; the linked sections in Configuration: Options carry defaults, types, cascade rules and validation semantics.

Option	Description
`--fail-fast`	Stop on first job failure. Overrides config value. See Options: Fail-fast and ignore-errors-on-exit.
`--processes=N`	Number of parallel processes. Overrides config value. `N` is a thread budget that is distributed across internally-parallel tools — see Options: Thread budget.
`--exclude-jobs=a,b`	Comma-separated list of jobs to skip.
`--only-jobs=a,b`	Comma-separated list of jobs to run (others skipped). Cannot combine with `--exclude-jobs`.
`--dry-run`	Show commands without executing. Works with all `--format` options.
`--format=FORMAT`	Output format: `text` (default), `json`, `junit`, `codeclimate`, `sarif`. See How-To: Output Formats.
`--output=PATH`	Write the structured payload to `PATH` (only for `json` / `junit` / `codeclimate` / `sarif`). Default: stdout. See Writing a report to a file.
`--report-FORMAT=PATH`	Emit an extra report file alongside whatever `--format` writes. One flag per format: `--report-json`, `--report-junit`, `--report-sarif`, `--report-codeclimate`. CLI overrides config entry by entry. See Multi-report.
`--no-reports`	Ignore the `reports` section from config (CLI `--report-*` flags still apply). PHPUnit `--no-coverage` style.
`--fast`	Fast mode — accelerable jobs analyze only staged files. See Execution Modes.
`--fast-branch`	Fast-branch mode — analyze files that differ from the main branch. The branch name comes from the `main-branch` option; see Execution Modes and Fast-branch fallback.
`--fast-dirty`	Fast-dirty mode — analyze the unified working tree: tracked files modified vs `HEAD` (staged or unstaged) ∪ non-ignored untracked. Ideal for AI agentic hooks and mid-review checks. Clean tree → all accelerable jobs skipped, exit 0 (no fallback to `full`). Mutually exclusive with `--fast`, `--fast-branch`, `--files`, `--files-from`. See Fast-dirty mode.
`--files=a,b,c`	Files mode — accelerable jobs analyze only the explicit list (CSV). Mutually exclusive with `--files-from`, `--fast`, `--fast-branch`, `--fast-dirty`. See How-To: --files / --files-from.
`--files-from=PATH`	Files mode — read the list of paths from `PATH` (one per line; `#` comments and blanks ignored; UTF-8 + CRLF tolerated). Use this when the list exceeds the shell `ARG_MAX` or comes from `git diff --name-only`.
`--exclude-pattern=glob1,glob2`	Drop input paths that match any glob (``, `*`, `?`). Requires `--files` or `--files-from`. See How-To: --files / --files-from.
`--branch=X`	Override the detected branch name used to resolve `flows.<name>.on => [branch_pattern => …]`. Wins over `$GITHOOKS_BRANCH`, CI env vars (`CI_COMMIT_REF_NAME`, `GITHUB_REF_NAME`, …) and `git rev-parse --abbrev-ref HEAD`. Only meaningful when the flow declares `on`. See Branch-driven execution mode (`on`).
`--monitor`	Show thread usage report after execution. See Options: Thread budget.
`--warn-after=N` / `--fail-after=N`	Override flow-level time-budget thresholds (seconds). See Options: Time budget.
`--no-time-budget`	Disable both per-job and flow-level time evaluation for this run. Mixing with `--warn-after` / `--fail-after` emits a stderr warning and ignores them.
`--memory-warn-above=N` / `--memory-fail-above=N`	Override flow-level memory-budget thresholds (MB). See Options: Memory budget.
`--no-memory-budget`	Disable both per-job and flow-level memory evaluation for this run.
`--allocator=fifo\\|greedy`	Override the admission strategy. See Options: Allocator strategy.
`--stats`	Activate RSS sampling and the 5-column summary table after the run. See Options: Stats.
`--stats-sort=exec\\|name\\|type`	Sort the `--stats` table: `exec` (default, completion order), `name`, or `type`. A non-`exec` value adds a leading `#` column with the execution order. Text table only; JSON keeps execution order (see `executionOrder`).
`--no-ci`	Disable auto-detection of CI annotations (GitHub Actions / GitLab CI). See CI Annotations.
`--show-progress`	Force progress emission on stderr even when not a TTY. Useful in CI with `--format=json\\|junit\\|sarif\\|codeclimate` to make long pipelines visible in the runner log.
`--diag`	Print a runtime diagnostics block (githooks version, platform, CPU/cgroup limit, available memory, load averages, start timestamp) before the run. Opt-in locally; auto-on in CI regardless of the flag. See Runtime diagnostics.
`--config=PATH`	Path to configuration file.

Examples¶

githooks flow qa                                    # Run the 'qa' flow
githooks flow lint --fail-fast                      # Run with fail-fast
githooks flow qa --exclude-jobs=phpunit,phpcpd      # Skip specific jobs
githooks flow qa --only-jobs=phpstan_src,phpmd_src  # Run only these jobs
githooks flow qa --dry-run                          # Show commands without running
githooks flow qa --dry-run --format=json            # Dry-run with JSON output
githooks flow qa --processes=4                      # Run with 4 parallel processes
githooks flow qa --format=json                      # JSON v2 (AI / CI / scripts), to stdout
githooks flow qa --format=junit                     # JUnit XML for test reporting, to stdout
githooks flow qa --format=codeclimate               # GitLab Code Quality report, to stdout
githooks flow qa --format=sarif                     # SARIF 2.1.0, to stdout
githooks flow qa --format=sarif --output=reports/qa.sarif   # SARIF to a file
githooks flow qa --report-sarif=reports/qa.sarif --report-junit=reports/junit.xml \
                                                    # Multi-report: 4 formats in one run
                 --report-codeclimate=reports/cc.json --report-json=reports/qa.json
githooks flow qa --format=json --no-reports         # AI/script: JSON to stdout, no side-effect files
githooks flow qa --fast                             # Only staged files
githooks flow qa --fast-branch                      # Only branch diff files
githooks flow qa --fast-dirty                       # Working tree diff vs HEAD ∪ untracked
githooks flow ci --branch=master                    # Force branch for flows.ci.on resolution
githooks flow qa --files=src/User.php               # Files mode: explicit single file
githooks flow qa --files-from=changed.txt           # Files mode: from manifest
githooks flow qa --files-from=changed.txt --exclude-pattern='**/*Test.php'
                                                    # Drop tests from the manifest
githooks flow qa --monitor                          # Show thread usage report
githooks flow qa --diag                             # Print runtime diagnostics block first
githooks flow qa --no-ci                            # Opt out of CI annotations
githooks flow qa --config=qa/custom-githooks.php    # Use custom config

Structured output¶

--format=json emits JSON v2: top-level version, executionMode (reflects the actual --fast/--fast-branch/--fast-dirty flag), passed, failed, skipped, and a jobs array with type, exitCode, paths, skipped, skipReason, fixApplied, command and output. Jobs cancelled by --fail-fast appear with skipped: true and skipReason: "skipped by fail-fast".
--format=junit emits JUnit XML compatible with mikepenz/action-junit-report and similar. Skipped jobs emit <skipped> elements.
--format=codeclimate emits a GitLab Code Quality JSON array. location.path is relative to the CWD.
--format=sarif emits a SARIF 2.1.0 report for GitHub Code Scanning. artifactLocation.uri is relative to the CWD.

All four structured formats print to stdout by default. Pass --output=PATH to write the payload to a file instead (equivalent to --format=FORMAT > PATH for scripts that already rely on shell redirection).

stderr progress is TTY-aware¶

Progress lines (OK, Done., colours) write to stderr only when a TTY is attached (interactive terminal). From scripts, agents, pipes or CI stderr is silent by default — --format=json | jq … works without 2>/dev/null:

# No redirection needed — stderr is naturally empty off a TTY
githooks flow qa --format=json | jq '.jobs[] | select(.success == false)'

Force progress in long-running CI pipelines with --show-progress:

githooks flow qa --format=json --show-progress --output=reports/qa.json

--dry-run never emits progress (no real execution to measure). See How-To: Output Formats for the full schema and stderr rules.

Exit codes¶

Code	Meaning
`0`	All jobs passed.
`1`	One or more jobs failed.

Conditions header¶

flow prints a conditions header at the start of every run with the resolved options and their source — one row per option, aligned, every row carries its (source) parenthesis (including (default)):

Settings:
  processes     = 4     (cli)
  fail-fast     = false (default)
  mode          = full  (default)
  time-budget   = none  (default)
  memory-budget = none  (default)
  allocator     = fifo  (default)
  stats         = false (default)

The header writes to stdout in text mode and to stderr when a structured format is combined with --show-progress. Its machine-readable counterpart is the effectiveOptions block in JSON v2.