Add prek exec for running commands in a hook environment

[j178]

Closes #2475

[codecov]

Codecov Report

❌ Patch coverage is 98.44789% with 7 lines in your changes missing coverage. Please review.
✅ Project coverage is 93.60%. Comparing base (d5ec7be) to head (4507261).

Files with missing lines	Patch %	Lines
crates/prek/src/cli/exec.rs	93.44%	4 Missing ⚠️
crates/prek/src/languages/mod.rs	98.75%	2 Missing ⚠️
crates/prek/src/cli/run/selector.rs	92.85%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #2478      +/-   ##
==========================================
+ Coverage   93.57%   93.60%   +0.02%     
==========================================
  Files         130      131       +1     
  Lines       28002    28212     +210     
==========================================
+ Hits        26204    26407     +203     
- Misses       1798     1805       +7     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[Copilot]

Pull request overview

This PR adds a new prek exec subcommand to run an arbitrary command inside the environment prepared for a single configured hook, and refactors language backends so both prek run and prek exec share a common “execution environment” setup path.

Changes:

• Add prek exec <hook-selector> -- <command>... CLI plumbing, docs, and end-to-end tests (including Node env reuse and selector behavior).
• Introduce ExecutionEnvironment and refactor language backends to express environment setup separately from hook entry preparation, enabling environment reuse outside the hook-running pipeline.
• Improve command resolution semantics by threading an explicit cwd into resolve_command, including better handling of relative commands for exec.

Reviewed changes

Copilot reviewed 34 out of 34 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
docs/usage.md	Documents prek exec behavior, selector rules, and unsupported backends.
docs/reference/cli.md	Adds CLI reference entry/usage/options for prek exec.
crates/prek/tests/run.rs	Updates completion snapshot to include the new exec command.
crates/prek/tests/languages/node.rs	Adds test ensuring exec uses the hook’s installed Node environment/deps.
crates/prek/tests/exec.rs	Adds end-to-end tests for stdin/stdout inheritance, env application, selector ambiguity, exit status propagation, and unsupported languages.
crates/prek/tests/common/mod.rs	Adds TestContext::exec() helper for invoking prek exec in tests.
crates/prek/src/workspace.rs	Adds Workspace::config_files() and reuses it for config staging checks.
crates/prek/src/main.rs	Wires the new Command::Exec variant into the main command dispatcher.
crates/prek/src/languages/system.rs	Removes bespoke run implementation to rely on the shared default run path.
crates/prek/src/languages/swift.rs	Refactors Swift backend to provide execution_environment() (PATH setup) instead of a custom run.
crates/prek/src/languages/script.rs	Refactors Script backend to provide prepare_hook_entry() using the shared environment.
crates/prek/src/languages/rust/rust.rs	Refactors Rust backend to provide execution_environment() (PATH + CARGO_HOME, etc.).
crates/prek/src/languages/ruby/ruby.rs	Refactors Ruby backend to provide execution_environment() (GEM/BUNDLE env hygiene).
crates/prek/src/languages/r.rs	Refactors R backend to provide execution_environment() and prepare_hook_entry().
crates/prek/src/languages/python/python.rs	Refactors Python backend to provide execution_environment() (venv PATH/VIRTUAL_ENV).
crates/prek/src/languages/php.rs	Refactors PHP backend to provide execution_environment() (PATH setup).
crates/prek/src/languages/perl.rs	Refactors Perl backend to provide execution_environment() (PATH + perl env vars).
crates/prek/src/languages/node/node.rs	Refactors Node backend to provide execution_environment() (PATH/NODE_PATH/npm cache vars).
crates/prek/src/languages/mod.rs	Adds ExecutionEnvironment, default LanguageBackend::run, Language::exec, ensure_exec_supported, and updates resolve_command to accept cwd.
crates/prek/src/languages/lua.rs	Refactors Lua backend to provide execution_environment() (LUA_PATH/LUA_CPATH/PATH).
crates/prek/src/languages/haskell.rs	Refactors Haskell backend to provide execution_environment() (PATH setup).
crates/prek/src/languages/golang/golang.rs	Refactors Go backend to provide execution_environment() (PATH + Go env vars).
crates/prek/src/languages/dotnet/dotnet.rs	Refactors .NET backend to provide execution_environment() (PATH + DOTNET_ROOT).
crates/prek/src/languages/deno/deno.rs	Refactors Deno backend to provide execution_environment() (PATH + DENO_DIR).
crates/prek/src/languages/dart.rs	Refactors Dart backend to split execution_environment() from prepare_hook_entry() (packages config injection).
crates/prek/src/languages/coursier.rs	Refactors Coursier backend to provide execution_environment() (PATH + COURSIER_CACHE).
crates/prek/src/languages/conda.rs	Refactors Conda backend to provide execution_environment() (PATH + conda env vars).
crates/prek/src/languages/bun/bun.rs	Refactors Bun backend to provide execution_environment() (PATH + BUN_INSTALL).
crates/prek/src/hook_entry.rs	Threads cwd through entry resolution paths and exposes PreparedHookEntry::direct.
crates/prek/src/cli/run/selector.rs	Adds Selectors::from_include() for explicit selectors without skip env vars.
crates/prek/src/cli/run/run.rs	Reuses workspace.config_files() when tracking configs.
crates/prek/src/cli/mod.rs	Adds exec module, Command::Exec, and ExecArgs clap parsing.
crates/prek/src/cli/hook_impl.rs	Updates legacy hook command resolution to pass cwd into resolve_command.
crates/prek/src/cli/exec.rs	Implements prek exec: selector resolution, env preparation via install, and spawning the requested command.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 4507261cb8

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[prek-ci-bot]

📦 Cargo Bloat Comparison

Binary size change: +0.34% (29.5 MiB → 29.6 MiB)

Expand for cargo-bloat output

Head Branch Results

 File  .text     Size             Crate Name
 1.1%   2.3% 332.0KiB        aws_lc_sys aws_lc_0_43_0_aes_gcm_encrypt_avx512
 1.1%   2.3% 332.0KiB        aws_lc_sys aws_lc_0_43_0_aes_gcm_decrypt_avx512
 0.2%   0.5%  70.9KiB              prek <prek::cli::Command as clap_builder::derive::Subcommand>::augment_subcommands
 0.2%   0.4%  58.0KiB              prek <<prek::config::Config as serde_core::de::Deserialize>::deserialize::__Visitor as serde_core::de::Visitor>::visit_map::<<serde_saphyr::de::deserializer::YamlDeserializer as serde_core::de::Deserializer>::deserialize_map::MA>
 0.2%   0.4%  56.6KiB              prek prek::run::{closure#0}
 0.2%   0.3%  49.4KiB annotate_snippets annotate_snippets::renderer::render::render
 0.1%   0.3%  38.4KiB              prek prek::cli::run::run::run::{closure#0}
 0.1%   0.2%  34.3KiB              prek <prek::cli::RunOptions as clap_builder::derive::Args>::augment_args
 0.1%   0.2%  33.5KiB              prek <prek::languages::ruby::installer::RubyInstaller>::install::{closure#0}
 0.1%   0.2%  30.1KiB     granit_parser <granit_parser::scanner::Scanner<granit_parser::input::str::StrInput>>::fetch_more_tokens
 0.1%   0.2%  29.4KiB              prek <<prek::config::RemoteHook as serde_core::de::Deserialize>::deserialize::__Visitor as serde_core::de::Visitor>::visit_map::<<serde_saphyr::de::deserializer::YamlDeserializer as serde_core::de::Deserializer>::deserialize_map::MA>
 0.1%   0.2%  28.9KiB    cargo_metadata <&mut serde_json::de::Deserializer<serde_json::read::StrRead> as serde_core::de::Deserializer>::deserialize_struct::<<cargo_metadata::Package as serde_core::de::Deserialize>::deserialize::__Visitor>
 0.1%   0.2%  28.7KiB              prek <prek::languages::node::installer::NodeInstaller>::install::{closure#0}
 0.1%   0.2%  28.0KiB        aws_lc_sys aws_lc_0_43_0_edwards25519_scalarmuldouble_alt
 0.1%   0.2%  27.5KiB        aws_lc_sys aws_lc_0_43_0_edwards25519_scalarmuldouble
 0.1%   0.2%  26.9KiB              prek <prek::languages::deno::installer::DenoInstaller>::download::{closure#0}
 0.1%   0.2%  25.7KiB              prek prek::cli::try_repo::try_repo::{closure#0}
 0.1%   0.2%  25.6KiB              prek <<prek::config::LocalHook as serde_core::de::Deserialize>::deserialize::__Visitor as serde_core::de::Visitor>::visit_map::<<serde_saphyr::de::deserializer::YamlDeserializer as serde_core::de::Deserializer>::deserialize_map::MA>
 0.1%   0.2%  25.2KiB              prek <<prek::config::UpdateOptions as serde_core::de::Deserialize>::deserialize::__Visitor as serde_core::de::Visitor>::visit_map::<<serde_saphyr::de::deserializer::YamlDeserializer as serde_core::de::Deserializer>::deserialize_map::MA>
 0.1%   0.2%  24.9KiB               xml <xml::reader::parser::PullParser>::dispatch_token
42.3%  88.2%  12.5MiB                   And 26309 smaller methods. Use -n N to show more.
47.9% 100.0%  14.2MiB                   .text section size, the file size is 29.6MiB

Base Branch Results

 File  .text     Size             Crate Name
 1.1%   2.3% 332.0KiB        aws_lc_sys aws_lc_0_43_0_aes_gcm_encrypt_avx512
 1.1%   2.3% 332.0KiB        aws_lc_sys aws_lc_0_43_0_aes_gcm_decrypt_avx512
 0.2%   0.5%  68.8KiB              prek <prek::cli::Command as clap_builder::derive::Subcommand>::augment_subcommands
 0.2%   0.4%  58.0KiB              prek <<prek::config::Config as serde_core::de::Deserialize>::deserialize::__Visitor as serde_core::de::Visitor>::visit_map::<<serde_saphyr::de::deserializer::YamlDeserializer as serde_core::de::Deserializer>::deserialize_map::MA>
 0.2%   0.3%  49.4KiB annotate_snippets annotate_snippets::renderer::render::render
 0.1%   0.3%  38.9KiB              prek prek::run::{closure#0}
 0.1%   0.3%  38.7KiB              prek prek::cli::run::run::run::{closure#0}
 0.1%   0.2%  33.6KiB              prek <prek::cli::RunOptions as clap_builder::derive::Args>::augment_args
 0.1%   0.2%  32.8KiB              prek <prek::languages::ruby::installer::RubyInstaller>::install::{closure#0}
 0.1%   0.2%  30.1KiB     granit_parser <granit_parser::scanner::Scanner<granit_parser::input::str::StrInput>>::fetch_more_tokens
 0.1%   0.2%  29.4KiB              prek <<prek::config::RemoteHook as serde_core::de::Deserialize>::deserialize::__Visitor as serde_core::de::Visitor>::visit_map::<<serde_saphyr::de::deserializer::YamlDeserializer as serde_core::de::Deserializer>::deserialize_map::MA>
 0.1%   0.2%  28.6KiB    cargo_metadata <&mut serde_json::de::Deserializer<serde_json::read::StrRead> as serde_core::de::Deserializer>::deserialize_struct::<<cargo_metadata::Package as serde_core::de::Deserialize>::deserialize::__Visitor>
 0.1%   0.2%  28.0KiB        aws_lc_sys aws_lc_0_43_0_edwards25519_scalarmuldouble_alt
 0.1%   0.2%  27.5KiB        aws_lc_sys aws_lc_0_43_0_edwards25519_scalarmuldouble
 0.1%   0.2%  26.8KiB              prek <prek::languages::deno::installer::DenoInstaller>::download::{closure#0}
 0.1%   0.2%  25.6KiB              prek prek::cli::try_repo::try_repo::{closure#0}
 0.1%   0.2%  25.6KiB              prek <<prek::config::LocalHook as serde_core::de::Deserialize>::deserialize::__Visitor as serde_core::de::Visitor>::visit_map::<<serde_saphyr::de::deserializer::YamlDeserializer as serde_core::de::Deserializer>::deserialize_map::MA>
 0.1%   0.2%  25.2KiB              prek <<prek::config::UpdateOptions as serde_core::de::Deserialize>::deserialize::__Visitor as serde_core::de::Visitor>::visit_map::<<serde_saphyr::de::deserializer::YamlDeserializer as serde_core::de::Deserializer>::deserialize_map::MA>
 0.1%   0.2%  24.9KiB               xml <xml::reader::parser::PullParser>::dispatch_token
 0.1%   0.2%  24.0KiB     granit_parser <granit_parser::scanner::Scanner<serde_saphyr::de::buffered_input::ReaderInput>>::fetch_more_tokens
42.3%  88.3%  12.5MiB                   And 26230 smaller methods. Use -n N to show more.
47.9% 100.0%  14.1MiB                   .text section size, the file size is 29.5MiB

[prek-ci-bot]

⚡️ Hyperfine Benchmarks

Summary: 0 regressions, 0 improvements above the 10% threshold.

Environment

• OS: Linux 6.17.0-1020-azure
• CPU: 4 cores
• prek version: prek 0.4.12+3 (5ee0321 2026-08-04)
• Rust version: rustc 1.97.1 (8bab26f4f 2026-07-14)
• Hyperfine version: hyperfine 1.20.0

CLI Commands

Benchmarking basic commands in the main repo:

prek --version

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
prek-base --version	1.7 ± 0.1	1.6	2.0	1.00
prek-head --version	1.7 ± 0.1	1.6	2.6	1.00 ± 0.08

prek list

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
prek-base list	7.3 ± 0.2	7.0	7.8	1.00
prek-head list	7.4 ± 0.1	7.0	7.7	1.02 ± 0.03

prek validate-config .pre-commit-config.yaml

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
prek-base validate-config .pre-commit-config.yaml	2.5 ± 0.1	2.4	2.8	1.00
prek-head validate-config .pre-commit-config.yaml	2.5 ± 0.1	2.4	2.8	1.00 ± 0.06

prek sample-config

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
prek-base sample-config	2.0 ± 0.1	1.9	2.2	1.00 ± 0.04
prek-head sample-config	2.0 ± 0.0	1.9	2.1	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	26.6 ± 1.7	23.8	29.7	1.05 ± 0.07
prek-head run --all-files	25.3 ± 0.6	24.3	25.9	1.00

prek run --all-files (warm - with cache)

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
prek-base run --all-files	26.3 ± 1.0	24.4	28.3	1.05 ± 0.09
prek-head run --all-files	25.1 ± 2.0	22.7	30.1	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	24.2 ± 0.8	22.1	26.3	1.00
prek-head run --all-files	25.3 ± 1.6	22.6	32.6	1.04 ± 0.08

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	8.5 ± 0.3	7.8	9.2	1.00
prek-head run trailing-whitespace --all-files	8.6 ± 0.2	8.4	9.0	1.02 ± 0.04

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	7.9 ± 0.4	7.0	8.9	1.03 ± 0.08
prek-head run end-of-file-fixer --all-files	7.6 ± 0.4	6.9	8.6	1.00

prek run check-json --all-files

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
prek-base run check-json --all-files	5.6 ± 0.2	5.3	6.2	1.00
prek-head run check-json --all-files	5.6 ± 0.2	5.3	5.9	1.01 ± 0.04

prek run check-yaml --all-files

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
prek-base run check-yaml --all-files	5.4 ± 0.1	5.2	5.6	1.00
prek-head run check-yaml --all-files	5.5 ± 0.1	5.3	5.8	1.02 ± 0.03

prek run check-toml --all-files

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
prek-base run check-toml --all-files	6.0 ± 0.3	5.5	7.0	1.07 ± 0.07
prek-head run check-toml --all-files	5.6 ± 0.2	5.2	6.0	1.00

prek run check-xml --all-files

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
prek-base run check-xml --all-files	5.5 ± 0.4	5.0	7.5	1.00
prek-head run check-xml --all-files	5.7 ± 1.9	5.1	15.7	1.04 ± 0.36

prek run detect-private-key --all-files

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
prek-base run detect-private-key --all-files	7.7 ± 0.4	7.0	8.9	1.00
prek-head run detect-private-key --all-files	7.7 ± 0.5	7.0	8.8	1.01 ± 0.08

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	10.0 ± 0.6	8.8	11.2	1.00
prek-head run fix-byte-order-marker --all-files	10.3 ± 0.7	9.0	11.4	1.02 ± 0.09

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	3.4 ± 0.1	3.3	3.7	1.03 ± 0.05
prek-head install-hooks	3.3 ± 0.1	3.3	3.4	1.00

prek install-hooks (warm - with cache)

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
prek-base install-hooks	3.3 ± 0.0	3.2	3.3	1.00
prek-head install-hooks	3.4 ± 0.1	3.2	3.5	1.03 ± 0.04

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	16.0 ± 0.4	15.6	17.3	1.00
prek-head run	16.1 ± 0.3	15.8	16.6	1.00 ± 0.03

prek run --files '*.json' (specific file type)

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
prek-base run --files '*.json'	3.9 ± 0.1	3.7	4.0	1.00
prek-head run --files '*.json'	4.0 ± 0.1	3.8	4.5	1.03 ± 0.04

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	4.9 ± 0.2	4.8	5.6	1.00
prek-head run --dry-run --all-files	5.0 ± 0.1	4.8	5.3	1.01 ± 0.04

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	5.8 ± 0.1	5.7	6.0	1.00
prek-head run check-hooks-apply --all-files	5.8 ± 0.2	5.6	6.3	1.00 ± 0.04

prek run check-useless-excludes --all-files

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
prek-base run check-useless-excludes --all-files	5.7 ± 0.1	5.6	6.1	1.00
prek-head run check-useless-excludes --all-files	5.8 ± 0.1	5.6	5.9	1.01 ± 0.03

prek run identity --all-files

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
prek-base run identity --all-files	5.0 ± 0.1	4.9	5.4	1.00
prek-head run identity --all-files	5.1 ± 0.7	4.8	7.5	1.02 ± 0.13