Fallback to manual stage for hooks specified directly in command line (#1185)

* feat(run): assume stage based on selected hooks

* fix(run): don't clone eagerly

* Remove fallback to `--all-files`, add tests

* Generate cli docs

* Improve wording

---------

Co-authored-by: Jo <[email protected]>

Author: drainpixie

docs/cli.md

@@ -204,8 +204,9 @@ prek run [OPTIONS] [HOOK|PROJECT]...
 </dd><dt id="prek-run--files"><a href="#prek-run--files"><code>--files</code></a> <i>files</i></dt><dd><p>Specific filenames to run hooks on</p>
 </dd><dt id="prek-run--from-ref"><a href="#prek-run--from-ref"><code>--from-ref</code></a>, <code>--source</code>, <code>-s</code> <i>from-ref</i></dt><dd><p>The original ref in a <code>&lt;from_ref&gt;...&lt;to_ref&gt;</code> diff expression. Files changed in this diff will be run through the hooks</p>
 </dd><dt id="prek-run--help"><a href="#prek-run--help"><code>--help</code></a>, <code>-h</code></dt><dd><p>Display the concise help for this command</p>
-</dd><dt id="prek-run--hook-stage"><a href="#prek-run--hook-stage"><code>--hook-stage</code></a> <i>hook-stage</i></dt><dd><p>The stage during which the hook is fired</p>
-<p>[default: pre-commit]</p><p>Possible values:</p>
+</dd><dt id="prek-run--hook-stage"><a href="#prek-run--hook-stage"><code>--hook-stage</code></a> <i>hook-stage</i></dt><dd><p>The stage during which the hook is fired.</p>
+<p>When specified, only hooks configured for that stage (for example <code>manual</code>, <code>pre-commit</code>, or <code>pre-commit</code>) will run. Defaults to <code>pre-commit</code> if not specified. For hooks specified directly in the command line, fallback to <code>manual</code> stage if no hooks found for <code>pre-commit</code> stage.</p>
+<p>Possible values:</p>
 <ul>
 <li><code>manual</code></li>
 <li><code>commit-msg</code></li>
@@ -761,8 +762,9 @@ prek try-repo [OPTIONS] <REPO> [HOOK|PROJECT]...
 </dd><dt id="prek-try-repo--files"><a href="#prek-try-repo--files"><code>--files</code></a> <i>files</i></dt><dd><p>Specific filenames to run hooks on</p>
 </dd><dt id="prek-try-repo--from-ref"><a href="#prek-try-repo--from-ref"><code>--from-ref</code></a>, <code>--source</code>, <code>-s</code> <i>from-ref</i></dt><dd><p>The original ref in a <code>&lt;from_ref&gt;...&lt;to_ref&gt;</code> diff expression. Files changed in this diff will be run through the hooks</p>
 </dd><dt id="prek-try-repo--help"><a href="#prek-try-repo--help"><code>--help</code></a>, <code>-h</code></dt><dd><p>Display the concise help for this command</p>
-</dd><dt id="prek-try-repo--hook-stage"><a href="#prek-try-repo--hook-stage"><code>--hook-stage</code></a> <i>hook-stage</i></dt><dd><p>The stage during which the hook is fired</p>
-<p>[default: pre-commit]</p><p>Possible values:</p>
+</dd><dt id="prek-try-repo--hook-stage"><a href="#prek-try-repo--hook-stage"><code>--hook-stage</code></a> <i>hook-stage</i></dt><dd><p>The stage during which the hook is fired.</p>
+<p>When specified, only hooks configured for that stage (for example <code>manual</code>, <code>pre-commit</code>, or <code>pre-commit</code>) will run. Defaults to <code>pre-commit</code> if not specified. For hooks specified directly in the command line, fallback to <code>manual</code> stage if no hooks found for <code>pre-commit</code> stage.</p>
+<p>Possible values:</p>
 <ul>
 <li><code>manual</code></li>
 <li><code>commit-msg</code></li>

src/cli/hook_impl.rs

@@ -112,7 +112,7 @@ pub(crate) async fn hook_impl(
         config,
         includes,
         skips,
-        hook_type.into(),
+        Some(hook_type.into()),
         run_args.from_ref,
         run_args.to_ref,
         run_args.all_files,

src/cli/mod.rs

@@ -445,8 +445,13 @@ pub(crate) struct RunArgs {
     pub(crate) last_commit: bool,
 
     /// The stage during which the hook is fired.
-    #[arg(long, default_value_t = Stage::PreCommit, value_enum)]
-    pub(crate) hook_stage: Stage,
+    ///
+    /// When specified, only hooks configured for that stage (for example `manual`,
+    /// `pre-commit`, or `pre-commit`) will run.
+    /// Defaults to `pre-commit` if not specified.
+    /// For hooks specified directly in the command line, fallback to `manual` stage if no hooks found for `pre-commit` stage.
+    #[arg(long, value_enum)]
+    pub(crate) hook_stage: Option<Stage>,
 
     /// When hooks fail, run `git diff` directly afterward.
     #[arg(long)]

src/cli/run/run.rs

@@ -36,7 +36,7 @@ pub(crate) async fn run(
     config: Option<PathBuf>,
     includes: Vec<String>,
     skips: Vec<String>,
-    hook_stage: Stage,
+    hook_stage: Option<Stage>,
     from_ref: Option<String>,
     to_ref: Option<String>,
     all_files: bool,
@@ -59,7 +59,7 @@ pub(crate) async fn run(
     };
 
     // Prevent recursive post-checkout hooks.
-    if hook_stage == Stage::PostCheckout
+    if hook_stage == Some(Stage::PostCheckout)
         && EnvVars::is_set(EnvVars::PREK_INTERNAL__SKIP_POST_CHECKOUT)
     {
         return Ok(ExitStatus::Success);
@@ -91,15 +91,15 @@ pub(crate) async fn run(
         .init_hooks(store, Some(&reporter))
         .await
         .context("Failed to init hooks")?;
-    let filtered_hooks: Vec<_> = hooks
+    let selected_hooks: Vec<_> = hooks
         .into_iter()
         .filter(|h| selectors.matches_hook(h))
         .map(Arc::new)
         .collect();
 
     selectors.report_unused();
 
-    if filtered_hooks.is_empty() {
+    if selected_hooks.is_empty() {
         writeln!(
             printer.stderr(),
             "{}: No hooks found after filtering with the given selectors",
@@ -117,10 +117,32 @@ pub(crate) async fn run(
         return Ok(ExitStatus::Failure);
     }
 
-    let filtered_hooks = filtered_hooks
-        .into_iter()
-        .filter(|h| h.stages.contains(hook_stage))
-        .collect::<Vec<_>>();
+    let (filtered_hooks, hook_stage) = if let Some(hook_stage) = hook_stage {
+        let hooks = selected_hooks
+            .iter()
+            .filter(|h| h.stages.contains(hook_stage))
+            .cloned()
+            .collect::<Vec<_>>();
+        (hooks, hook_stage)
+    } else {
+        // Try filtering by `pre-commit` stage first.
+        let mut hook_stage = Stage::PreCommit;
+        let mut hooks = selected_hooks
+            .iter()
+            .filter(|h| h.stages.contains(Stage::PreCommit))
+            .cloned()
+            .collect::<Vec<_>>();
+        if hooks.is_empty() && selectors.includes_only_hook_targets() {
+            // If no hooks found for `pre-commit` stage, try fallback to `manual` stage for hooks specified directly.
+            hook_stage = Stage::Manual;
+            hooks = selected_hooks
+                .iter()
+                .filter(|h| h.stages.contains(Stage::Manual))
+                .cloned()
+                .collect();
+        }
+        (hooks, hook_stage)
+    };
 
     if filtered_hooks.is_empty() {
         writeln!(

src/cli/run/selector.rs

@@ -202,6 +202,16 @@ impl Selectors {
         })
     }
 
+    pub(crate) fn includes_only_hook_targets(&self) -> bool {
+        !self.includes.is_empty()
+            && self.includes.iter().all(|s| {
+                matches!(
+                    s.expr,
+                    SelectorExpr::HookId(_) | SelectorExpr::ProjectHook { .. }
+                )
+            })
+    }
+
     /// Check if a hook matches any of the selection criteria.
     pub(crate) fn matches_hook(&self, hook: &Hook) -> bool {
         let mut usage = self.usage.lock().unwrap();

tests/run.rs

@@ -576,6 +576,88 @@ fn stage() {
     "#);
 }
 
+#[test]
+fn fallback_to_manual_stage() {
+    let context = TestContext::new();
+    context.init_project();
+    context.write_pre_commit_config(indoc::indoc! {r"
+        repos:
+          - repo: local
+            hooks:
+              - id: manual-only
+                name: manual-only
+                language: system
+                entry: echo manual-only
+                stages: [ manual ]
+              - id: another-manual
+                name: another-manual
+                language: system
+                entry: echo another-manual
+                stages: [ manual ]
+              - id: default-stage
+                name: default-stage
+                language: system
+                entry: echo default-stage
+              - id: pre-push
+                name: pre-push
+                language: system
+                entry: echo pre-push
+                stages: [ pre-push ]
+    "});
+    context.git_add(".");
+
+    // With pre-commit hooks present, default `prek run` stays on pre-commit.
+    cmd_snapshot!(context.filters(), context.run(), @r"
+    success: true
+    exit_code: 0
+    ----- stdout -----
+    default-stage............................................................Passed
+
+    ----- stderr -----
+    ");
+
+    // Explicit `--hook-stage pre-commit` keeps execution scoped to that stage.
+    cmd_snapshot!(context.filters(), context.run().arg("--hook-stage").arg("pre-commit").arg("default-stage").arg("manual-only"), @r"
+    success: true
+    exit_code: 0
+    ----- stdout -----
+    default-stage............................................................Passed
+
+    ----- stderr -----
+    ");
+
+    // Selecting manual + pre-commit hooks still runs only the pre-commit ones.
+    cmd_snapshot!(context.filters(), context.run().arg("manual-only").arg("default-stage"), @r"
+    success: true
+    exit_code: 0
+    ----- stdout -----
+    default-stage............................................................Passed
+
+    ----- stderr -----
+    ");
+
+    // Selecting only manual hooks should still succeed via fallback.
+    cmd_snapshot!(context.filters(), context.run().arg("manual-only").arg("another-manual"), @r"
+    success: true
+    exit_code: 0
+    ----- stdout -----
+    manual-only..............................................................Passed
+    another-manual...........................................................Passed
+
+    ----- stderr -----
+    ");
+
+    // Mixing `pre-push` and manual selectors still runs the manual hook via fallback.
+    cmd_snapshot!(context.filters(), context.run().arg("pre-push").arg("manual-only"), @r"
+    success: true
+    exit_code: 0
+    ----- stdout -----
+    manual-only..............................................................Passed
+
+    ----- stderr -----
+    ");
+}
+
 /// Test global `files`, `exclude`, and hook level `files`, `exclude`.
 #[test]
 fn files_and_exclude() -> Result<()> {