Print hook description on failure with --verbose#2353
Conversation
Codecov Report❌ Patch coverage is
Additional details and impacted files@@ Coverage Diff @@
## master #2353 +/- ##
==========================================
- Coverage 93.33% 88.47% -4.86%
==========================================
Files 128 128
Lines 27262 27272 +10
==========================================
- Hits 25446 24130 -1316
- Misses 1816 3142 +1326 ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
There was a problem hiding this comment.
Pull request overview
This PR extends prek’s verbose mode so that, when a hook fails, prek prints the hook’s configured description alongside the existing failure details. It also adds a PREK_VERBOSE environment variable to enable the same behavior for Git-triggered hooks (e.g., git commit), where CLI flags can’t be forwarded to the hook shim.
Changes:
- Print
- description: ...on hook failure when verbose mode is enabled (CLI--verbose/-v, per-hook verbosity, or viaPREK_VERBOSEfor Git hook shims). - Add
PREK_VERBOSEenv var support and thread verbose through thehook-implexecution path. - Update schema/docs and add integration tests covering both
prek runand Git-hook (hook-impl) paths.
Reviewed changes
Copilot reviewed 13 out of 13 changed files in this pull request and generated no comments.
Show a summary per file
| File | Description |
|---|---|
crates/prek/src/cli/run/run.rs |
Prints hook description in the failure detail block when verbose mode is enabled. |
crates/prek-consts/src/env_vars.rs |
Adds PREK_VERBOSE environment variable constant. |
crates/prek/src/cli/mod.rs |
Wires PREK_VERBOSE into the global --verbose flag and updates help text. |
crates/prek/src/cli/hook_impl.rs |
Threads a verbose boolean into hook-impl and passes it through to cli::run. |
crates/prek/src/main.rs |
Passes global verbose state into the hook-impl command handler. |
crates/prek/src/config.rs |
Updates the description field doc comment to reflect new surfaced behavior. |
crates/prek/tests/run.rs |
Adds integration tests for description printing with --verbose and PREK_VERBOSE. |
crates/prek/tests/hook_impl.rs |
Adds an end-to-end Git hook path test verifying PREK_VERBOSE behavior. |
docs/usage.md |
Documents using --verbose / PREK_VERBOSE to see hook descriptions on failure. |
docs/authoring-hooks.md |
Notes that description can be printed on failure when verbose is enabled. |
docs/reference/configuration.md |
Documents description printing behavior for verbose mode. |
docs/reference/cli.md |
Regenerated CLI reference reflecting updated --verbose help text and env var. |
prek.schema.json |
Regenerated schema: updates description field documentation. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
📦 Cargo Bloat ComparisonBinary size change: -0.68% (29.2 MiB → 29.0 MiB) Expand for cargo-bloat outputHead Branch ResultsBase Branch Results |
⚡️ Hyperfine BenchmarksSummary: 1 regressions, 0 improvements above the 10% threshold. Environment
CLI CommandsBenchmarking basic commands in the main repo:
|
| Command | Mean [ms] | Min [ms] | Max [ms] | Relative |
|---|---|---|---|---|
prek-base --version |
2.6 ± 0.1 | 2.4 | 3.2 | 1.08 ± 0.09 |
prek-head --version |
2.4 ± 0.2 | 2.2 | 3.1 | 1.00 |
prek list
| Command | Mean [ms] | Min [ms] | Max [ms] | Relative |
|---|---|---|---|---|
prek-base list |
10.8 ± 0.3 | 10.1 | 11.6 | 1.02 ± 0.05 |
prek-head list |
10.5 ± 0.3 | 9.9 | 11.4 | 1.00 |
prek validate-config .pre-commit-config.yaml
| Command | Mean [ms] | Min [ms] | Max [ms] | Relative |
|---|---|---|---|---|
prek-base validate-config .pre-commit-config.yaml |
4.3 ± 0.2 | 3.9 | 4.7 | 1.07 ± 0.06 |
prek-head validate-config .pre-commit-config.yaml |
4.0 ± 0.2 | 3.8 | 4.5 | 1.00 |
prek sample-config
| Command | Mean [ms] | Min [ms] | Max [ms] | Relative |
|---|---|---|---|---|
prek-base sample-config |
3.2 ± 0.1 | 3.0 | 3.6 | 1.09 ± 0.05 |
prek-head sample-config |
3.0 ± 0.1 | 2.9 | 3.2 | 1.00 |
Cold vs Warm Runs
Comparing first run (cold) vs subsequent runs (warm cache):
prek run --all-files (cold - no cache)
| Command | Mean [ms] | Min [ms] | Max [ms] | Relative |
|---|---|---|---|---|
prek-base run --all-files |
80.3 ± 3.2 | 75.9 | 85.7 | 1.00 ± 0.05 |
prek-head run --all-files |
80.0 ± 2.9 | 74.4 | 83.5 | 1.00 |
prek run --all-files (warm - with cache)
| Command | Mean [ms] | Min [ms] | Max [ms] | Relative |
|---|---|---|---|---|
prek-base run --all-files |
79.9 ± 3.7 | 73.8 | 84.6 | 1.03 ± 0.06 |
prek-head run --all-files |
77.4 ± 3.1 | 71.4 | 82.5 | 1.00 |
Full Hook Suite
Running the builtin hook suite on the benchmark workspace:
prek run --all-files (full builtin hook suite)
| Command | Mean [ms] | Min [ms] | Max [ms] | Relative |
|---|---|---|---|---|
prek-base run --all-files |
78.2 ± 3.2 | 72.0 | 85.4 | 1.01 ± 0.06 |
prek-head run --all-files |
77.4 ± 3.6 | 71.9 | 93.8 | 1.00 |
Individual Hook Performance
Benchmarking each hook individually on the test repo:
prek run trailing-whitespace --all-files
| Command | Mean [ms] | Min [ms] | Max [ms] | Relative |
|---|---|---|---|---|
prek-base run trailing-whitespace --all-files |
21.3 ± 0.5 | 20.6 | 22.5 | 1.02 ± 0.03 |
prek-head run trailing-whitespace --all-files |
21.0 ± 0.4 | 20.1 | 22.2 | 1.00 |
prek run end-of-file-fixer --all-files
| Command | Mean [ms] | Min [ms] | Max [ms] | Relative |
|---|---|---|---|---|
prek-base run end-of-file-fixer --all-files |
27.9 ± 2.8 | 24.3 | 34.9 | 1.00 |
prek-head run end-of-file-fixer --all-files |
28.0 ± 2.1 | 25.1 | 31.5 | 1.00 ± 0.13 |
prek run check-json --all-files
| Command | Mean [ms] | Min [ms] | Max [ms] | Relative |
|---|---|---|---|---|
prek-base run check-json --all-files |
8.9 ± 0.4 | 8.4 | 9.9 | 1.07 ± 0.05 |
prek-head run check-json --all-files |
8.4 ± 0.2 | 8.0 | 8.8 | 1.00 |
prek run check-yaml --all-files
| Command | Mean [ms] | Min [ms] | Max [ms] | Relative |
|---|---|---|---|---|
prek-base run check-yaml --all-files |
8.6 ± 1.5 | 7.9 | 14.7 | 1.05 ± 0.19 |
prek-head run check-yaml --all-files |
8.2 ± 0.2 | 7.8 | 8.8 | 1.00 |
prek run check-toml --all-files
| Command | Mean [ms] | Min [ms] | Max [ms] | Relative |
|---|---|---|---|---|
prek-base run check-toml --all-files |
8.7 ± 0.3 | 8.2 | 9.5 | 1.09 ± 0.05 |
prek-head run check-toml --all-files |
8.0 ± 0.3 | 7.6 | 8.4 | 1.00 |
prek run check-xml --all-files
| Command | Mean [ms] | Min [ms] | Max [ms] | Relative |
|---|---|---|---|---|
prek-base run check-xml --all-files |
8.4 ± 0.4 | 7.8 | 9.2 | 1.04 ± 0.06 |
prek-head run check-xml --all-files |
8.1 ± 0.4 | 7.6 | 9.0 | 1.00 |
prek run detect-private-key --all-files
| Command | Mean [ms] | Min [ms] | Max [ms] | Relative |
|---|---|---|---|---|
prek-base run detect-private-key --all-files |
14.0 ± 1.1 | 12.1 | 16.2 | 1.01 ± 0.11 |
prek-head run detect-private-key --all-files |
14.0 ± 1.0 | 11.8 | 15.6 | 1.00 |
prek run fix-byte-order-marker --all-files
| Command | Mean [ms] | Min [ms] | Max [ms] | Relative |
|---|---|---|---|---|
prek-base run fix-byte-order-marker --all-files |
19.0 ± 0.7 | 17.7 | 20.4 | 1.00 |
prek-head run fix-byte-order-marker --all-files |
29.4 ± 34.0 | 17.4 | 186.7 | 1.55 ± 1.79 |
prek run fix-byte-order-marker --all-files: 54.8500% slower
Installation Performance
Benchmarking hook installation (fast path hooks skip Python setup):
prek install-hooks (cold - no cache)
| Command | Mean [ms] | Min [ms] | Max [ms] | Relative |
|---|---|---|---|---|
prek-base install-hooks |
5.2 ± 0.1 | 5.1 | 5.2 | 1.05 ± 0.02 |
prek-head install-hooks |
4.9 ± 0.1 | 4.8 | 5.0 | 1.00 |
prek install-hooks (warm - with cache)
| Command | Mean [ms] | Min [ms] | Max [ms] | Relative |
|---|---|---|---|---|
prek-base install-hooks |
5.3 ± 0.1 | 5.1 | 5.4 | 1.09 ± 0.03 |
prek-head install-hooks |
4.9 ± 0.1 | 4.8 | 4.9 | 1.00 |
File Filtering/Scoping Performance
Testing different file selection modes:
prek run (staged files only)
| Command | Mean [ms] | Min [ms] | Max [ms] | Relative |
|---|---|---|---|---|
prek-base run |
40.1 ± 0.8 | 39.0 | 42.3 | 1.00 |
prek-head run |
40.9 ± 2.7 | 38.9 | 51.2 | 1.02 ± 0.07 |
prek run --files '*.json' (specific file type)
| Command | Mean [ms] | Min [ms] | Max [ms] | Relative |
|---|---|---|---|---|
prek-base run --files '*.json' |
9.0 ± 0.1 | 8.8 | 9.2 | 1.02 ± 0.02 |
prek-head run --files '*.json' |
8.7 ± 0.2 | 8.4 | 9.1 | 1.00 |
Workspace Discovery & Initialization
Benchmarking hook discovery and initialization overhead:
prek run --dry-run --all-files (measures init overhead)
| Command | Mean [ms] | Min [ms] | Max [ms] | Relative |
|---|---|---|---|---|
prek-base run --dry-run --all-files |
7.8 ± 0.2 | 7.5 | 8.5 | 1.05 ± 0.03 |
prek-head run --dry-run --all-files |
7.5 ± 0.1 | 7.3 | 7.8 | 1.00 |
Meta Hooks Performance
Benchmarking meta hooks separately:
prek run check-hooks-apply --all-files
| Command | Mean [ms] | Min [ms] | Max [ms] | Relative |
|---|---|---|---|---|
prek-base run check-hooks-apply --all-files |
13.4 ± 0.2 | 13.2 | 13.9 | 1.06 ± 0.06 |
prek-head run check-hooks-apply --all-files |
12.7 ± 0.7 | 11.6 | 13.5 | 1.00 |
prek run check-useless-excludes --all-files
| Command | Mean [ms] | Min [ms] | Max [ms] | Relative |
|---|---|---|---|---|
prek-base run check-useless-excludes --all-files |
11.7 ± 0.2 | 11.5 | 12.3 | 1.00 |
prek-head run check-useless-excludes --all-files |
12.2 ± 1.7 | 11.2 | 17.6 | 1.04 ± 0.14 |
prek run identity --all-files
| Command | Mean [ms] | Min [ms] | Max [ms] | Relative |
|---|---|---|---|---|
prek-base run identity --all-files |
11.1 ± 0.2 | 10.8 | 11.6 | 1.01 ± 0.02 |
prek-head run identity --all-files |
10.9 ± 0.1 | 10.8 | 11.3 | 1.00 |
When --verbose (or the new PREK_VERBOSE env var) is enabled and a hook fails, prek now prints the hook's `description` field alongside the existing hook id/ duration/exit code details. This helps users understand why a hook failed without needing to dig through prek.toml/.pre-commit-config.yaml. The PREK_VERBOSE env var lets this work for Git-triggered hooks too (e.g. `PREK_VERBOSE=1 git commit`), since Git can't forward CLI flags to the installed hook shim. Adds tests covering both `prek run --verbose` and the PREK_VERBOSE env var via a real git-hook invocation, and updates docs/reference/cli.md, docs/reference/configuration.md, docs/authoring-hooks.md, docs/usage.md, and prek.schema.json accordingly. Co-authored-by: Copilot <[email protected]>
50c040f to
0aa6052
Compare
| Free-form description shown in listings / metadata. When `--verbose` (or the `PREK_VERBOSE` | ||
| environment variable) is enabled, this description is also printed if the hook fails, to help | ||
| explain why the hook exists and what it checks. |
| | `fail_fast` | No | No | boolean | Stop the run immediately if this hook fails. | | ||
| | `pass_filenames` | No | No | boolean or positive integer | Control whether, or how many, matching filenames are passed. | | ||
| | `description` | No | No | string | Free-form metadata shown in listings. | | ||
| | `description` | No | No | string | Free-form metadata shown in listings; printed on failure when `--verbose` is enabled. | |
| }, | ||
| "description": { | ||
| "description": "A description of the hook. For metadata only.", | ||
| "description": "A description of the hook, shown in listings and, when `--verbose` is enabled, printed\nif the hook fails to help explain the failure.", |
| }, | ||
| "description": { | ||
| "description": "A description of the hook. For metadata only.", | ||
| "description": "A description of the hook, shown in listings and, when `--verbose` is enabled, printed\nif the hook fails to help explain the failure.", |
| }, | ||
| "description": { | ||
| "description": "A description of the hook. For metadata only.", | ||
| "description": "A description of the hook, shown in listings and, when `--verbose` is enabled, printed\nif the hook fails to help explain the failure.", |
| }, | ||
| "description": { | ||
| "description": "A description of the hook. For metadata only.", | ||
| "description": "A description of the hook, shown in listings and, when `--verbose` is enabled, printed\nif the hook fails to help explain the failure.", |
Co-authored-by: Copilot Autofix powered by AI <[email protected]>
| if status == RunStatus::Failed | ||
| && (self.verbose || result.hook.verbose) | ||
| && let Some(description) = result.hook.description.as_deref() | ||
| { | ||
| writeln!( | ||
| stdout, | ||
| "{detail_prefix}{}", | ||
| format!("- description: {description}").dimmed() | ||
| )?; | ||
| } |
| | `fail_fast` | No | No | boolean | Stop the run immediately if this hook fails. | | ||
| | `pass_filenames` | No | No | boolean or positive integer | Control whether, or how many, matching filenames are passed. | | ||
| | `description` | No | No | string | Free-form metadata shown in listings. | | ||
| | `description` | No | No | string | Free-form metadata shown in listings; printed on failure when `--verbose` is enabled. | |
| Free-form description shown in listings / metadata. When `--verbose` (or the `PREK_VERBOSE` | ||
| environment variable) is enabled, this description is also printed if the hook fails, to help | ||
| explain why the hook exists and what it checks. |
| }, | ||
| "description": { | ||
| "description": "A description of the hook. For metadata only.", | ||
| "description": "A description of the hook, shown in listings and, when `--verbose` is enabled, printed\nif the hook fails to help explain the failure.", |
| }, | ||
| "description": { | ||
| "description": "A description of the hook. For metadata only.", | ||
| "description": "A description of the hook, shown in listings and, when `--verbose` is enabled, printed\nif the hook fails to help explain the failure.", |
| }, | ||
| "description": { | ||
| "description": "A description of the hook. For metadata only.", | ||
| "description": "A description of the hook, shown in listings and, when `--verbose` is enabled, printed\nif the hook fails to help explain the failure.", |
| }, | ||
| "description": { | ||
| "description": "A description of the hook. For metadata only.", | ||
| "description": "A description of the hook, shown in listings and, when `--verbose` is enabled, printed\nif the hook fails to help explain the failure.", |
Summary
When
--verbose(or the newPREK_VERBOSEenvironment variable) is enabled and a hook fails, prek now prints the hook'sdescriptionfield alongside the existing hook id/duration/exit code details. The goal is to help users understand why a hook failed without needing to dig throughprek.toml/.pre-commit-config.yaml. This is opt-in, but could become default behavior in the future.The
PREK_VERBOSEenv var lets this work for hooks triggered via Git (e.g.git commit) too, since Git has no way to forward CLI flags like--verboseto the installed hook shim.Changes
crates/prek/src/cli/run/run.rs: print- description: ...after- hook id: ...when a hook fails and verbose mode (global--verbose/-vor per-hookverbose: true) is active.crates/prek-consts/src/env_vars.rs: addedPREK_VERBOSEenv var, mirroring the existingPREK_QUIET.crates/prek/src/cli/mod.rs: wiredenv = EnvVars::PREK_VERBOSEonto the--verbosearg and updated its help text.crates/prek/src/cli/hook_impl.rs/crates/prek/src/main.rs: threadedverbosethroughhook-implso hooks invoked by Git shims respect it.crates/prek/src/config.rs: updated thedescriptionfield doc comment to mention it's now surfaced on failure.docs/usage.md,docs/authoring-hooks.md,docs/reference/configuration.md,docs/reference/cli.md(regenerated), andprek.schema.json(regenerated).Tests
crates/prek/tests/run.rs:verbose_prints_hook_description_on_failureandprek_verbose_env_var_prints_hook_description_on_failure.crates/prek/tests/hook_impl.rs:hook_impl_verbose_env_var_prints_hook_description, exercising the Git-hook (git commit) path end-to-end.cargo fmt --checkandcargo clippy --all-targetsare clean, and the fullrun/hook_implintegration test suites pass locally.