Allow pass_filenames to accept a positive integer

Setting `pass_filenames: n` limits each hook invocation to at most `n`
filenames, with multiple parallel invocations for larger file sets.
This mirrors the `-n` flag of `xargs` and is useful for tools that can
only process a limited number of files per invocation (typically, if a
limit applies, it is 1).

The existing boolean behaviour is preserved: `true` passes all filenames
(default) and `false` passes none. So this is a backwards compatible
change.

Resolves: #1471
Signed-off-by: JP-Ellis <josh@jpellis.me>

Author: JP-Ellis

crates/prek/src/cli/run/run.rs

@@ -21,7 +21,7 @@ use crate::cli::reporter::{HookInitReporter, HookInstallReporter, HookRunReporte
 use crate::cli::run::keeper::WorkTreeKeeper;
 use crate::cli::run::{CollectOptions, FileFilter, Selectors, collect_files};
 use crate::cli::{ExitStatus, RunExtraArgs};
-use crate::config::{Language, Stage};
+use crate::config::{Language, PassFilenames, Stage};
 use crate::fs::CWD;
 use crate::git::GIT_ROOT;
 use crate::hook::{Hook, InstallInfo, InstalledHook, Repo};
@@ -1019,11 +1019,12 @@ async fn run_hook(
     }
     let start = std::time::Instant::now();
 
-    let filenames = if hook.pass_filenames {
-        shuffle(&mut filenames);
-        filenames
-    } else {
-        vec![]
+    let filenames = match hook.pass_filenames {
+        PassFilenames::All | PassFilenames::Limited(_) => {
+            shuffle(&mut filenames);
+            filenames
+        }
+        PassFilenames::None => vec![],
     };
 
     let (exit_status, hook_output) = if dry_run {

crates/prek/src/config.rs

@@ -329,6 +329,68 @@ impl<'de> Deserialize<'de> for Stages {
     }
 }
 
+/// Controls whether filenames are appended to a hook's command line.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub(crate) enum PassFilenames {
+    /// Pass all matching filenames (default). Corresponds to `pass_filenames:
+    /// true`.
+    All,
+    /// Pass no filenames. Corresponds to `pass_filenames: false`.
+    None,
+    /// Pass at most `n` filenames per invocation. Corresponds to
+    /// `pass_filenames: n`.
+    Limited(std::num::NonZeroUsize),
+}
+
+impl<'de> Deserialize<'de> for PassFilenames {
+    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
+    where
+        D: Deserializer<'de>,
+    {
+        struct PassFilenamesVisitor;
+
+        impl serde::de::Visitor<'_> for PassFilenamesVisitor {
+            type Value = PassFilenames;
+
+            fn expecting(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
+                f.write_str("a boolean or a positive integer")
+            }
+
+            fn visit_bool<E: DeError>(self, v: bool) -> Result<PassFilenames, E> {
+                Ok(if v {
+                    PassFilenames::All
+                } else {
+                    PassFilenames::None
+                })
+            }
+
+            fn visit_u64<E: DeError>(self, v: u64) -> Result<PassFilenames, E> {
+                let n = usize::try_from(v)
+                    .ok()
+                    .and_then(std::num::NonZeroUsize::new)
+                    .ok_or_else(|| {
+                        E::custom(
+                            "pass_filenames must be a positive integer; use `false` to pass no filenames",
+                        )
+                    })?;
+                Ok(PassFilenames::Limited(n))
+            }
+
+            fn visit_i64<E: DeError>(self, v: i64) -> Result<PassFilenames, E> {
+                if v <= 0 {
+                    return Err(E::custom(
+                        "pass_filenames must be a positive integer; use `false` to pass no filenames",
+                    ));
+                }
+                #[allow(clippy::cast_sign_loss)]
+                self.visit_u64(v as u64)
+            }
+        }
+
+        deserializer.deserialize_any(PassFilenamesVisitor)
+    }
+}
+
 /// Common hook options.
 #[derive(Debug, Clone, Default, Deserialize)]
 #[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
@@ -363,7 +425,7 @@ pub(crate) struct HookOptions {
     pub fail_fast: Option<bool>,
     /// Append filenames that would be checked to the hook entry as arguments.
     /// Default is true.
-    pub pass_filenames: Option<bool>,
+    pub pass_filenames: Option<PassFilenames>,
     /// A description of the hook. For metadata only.
     pub description: Option<String>,
     /// Run the hook on a specific version of the language.

crates/prek/src/hook.rs

@@ -16,7 +16,7 @@ use tracing::trace;
 
 use crate::config::{
     self, BuiltinHook, Config, FilePattern, HookOptions, Language, LocalHook, ManifestHook,
-    MetaHook, RemoteHook, Stages, read_manifest,
+    MetaHook, PassFilenames, RemoteHook, Stages, read_manifest,
 };
 use crate::languages::version::LanguageRequest;
 use crate::languages::{extract_metadata, resolve_command};
@@ -324,7 +324,7 @@ impl HookBuilder {
         let exclude_types = options.exclude_types.unwrap_or_default();
         let always_run = options.always_run.unwrap_or(false);
         let fail_fast = options.fail_fast.unwrap_or(false);
-        let pass_filenames = options.pass_filenames.unwrap_or(true);
+        let pass_filenames = options.pass_filenames.unwrap_or(PassFilenames::All);
         let require_serial = options.require_serial.unwrap_or(false);
         let verbose = options.verbose.unwrap_or(false);
         let stages = options.stages.unwrap_or_default();
@@ -456,7 +456,7 @@ pub(crate) struct Hook {
     pub env: FxHashMap<String, String>,
     pub always_run: bool,
     pub fail_fast: bool,
-    pub pass_filenames: bool,
+    pub pass_filenames: PassFilenames,
     pub description: Option<String>,
     pub language_request: LanguageRequest,
     pub log_file: Option<String>,
@@ -838,7 +838,7 @@ mod tests {
     use prek_identify::tags;
     use rustc_hash::FxHashMap;
 
-    use crate::config::{HookOptions, Language, RemoteHook};
+    use crate::config::{HookOptions, Language, PassFilenames, RemoteHook};
     use crate::hook::HookSpec;
     use crate::languages::version::LanguageRequest;
     use crate::workspace::Project;
@@ -899,7 +899,7 @@ mod tests {
                 args: Some(vec!["--flag".to_string()]),
                 env: Some(override_env),
                 always_run: Some(true),
-                pass_filenames: Some(false),
+                pass_filenames: Some(PassFilenames::None),
                 verbose: Some(true),
                 description: Some("desc".to_string()),
                 ..Default::default()
@@ -974,7 +974,7 @@ mod tests {
             },
             always_run: true,
             fail_fast: false,
-            pass_filenames: false,
+            pass_filenames: None,
             description: Some(
                 "desc",
             ),

crates/prek/src/hooks/builtin_hooks/mod.rs

@@ -5,7 +5,7 @@ use anyhow::Result;
 use prek_identify::tags;
 
 use crate::cli::reporter::HookRunReporter;
-use crate::config::{BuiltinHook, HookOptions, Stage};
+use crate::config::{BuiltinHook, HookOptions, PassFilenames, Stage};
 use crate::hook::Hook;
 use crate::hooks::pre_commit_hooks;
 use crate::store::Store;
@@ -264,7 +264,7 @@ impl BuiltinHook {
                 entry: "no-commit-to-branch".to_string(),
                 priority: None,
                 options: HookOptions {
-                    pass_filenames: Some(false),
+                    pass_filenames: Some(PassFilenames::None),
                     always_run: Some(true),
                     ..Default::default()
                 },

crates/prek/src/run.rs

@@ -9,6 +9,7 @@ use prek_consts::env_vars::EnvVars;
 use rustc_hash::FxHashMap;
 use tracing::trace;
 
+use crate::config::PassFilenames;
 use crate::hook::Hook;
 
 pub(crate) static USE_COLOR: LazyLock<bool> =
@@ -143,7 +144,10 @@ impl<'a> Partitions<'a> {
         filenames: &'a [&'a Path],
         concurrency: usize,
     ) -> anyhow::Result<Self> {
-        let max_per_batch = max(4, filenames.len().div_ceil(concurrency));
+        let max_per_batch = match hook.pass_filenames {
+            PassFilenames::Limited(n) => n.get(),
+            _ => max(4, filenames.len().div_ceil(concurrency)),
+        };
         let mut arg_max = platform_max_cli_length();
 
         let cmd = Path::new(&entry[0]);

crates/prek/src/schema.rs

@@ -1,6 +1,6 @@
 use crate::config::{
-    BuiltinHook, BuiltinRepo, FilePattern, LocalRepo, MetaHook, MetaRepo, RemoteHook, RemoteRepo,
-    Repo, Stage, Stages,
+    BuiltinHook, BuiltinRepo, FilePattern, LocalRepo, MetaHook, MetaRepo, PassFilenames,
+    RemoteHook, RemoteRepo, Repo, Stage, Stages,
 };
 use std::borrow::Cow;
 
@@ -178,6 +178,25 @@ impl schemars::JsonSchema for FilePattern {
     }
 }
 
+impl schemars::JsonSchema for PassFilenames {
+    fn schema_name() -> std::borrow::Cow<'static, str> {
+        std::borrow::Cow::Borrowed("PassFilenames")
+    }
+
+    fn json_schema(_gen: &mut schemars::generate::SchemaGenerator) -> schemars::Schema {
+        schemars::json_schema!({
+            "description": "Whether to pass filenames to the hook. \
+            `true` passes all matching filenames (default), \
+            `false` passes none, and \
+            a positive integer limits each invocation to at most that many filenames.",
+            "oneOf": [
+                {"type": "boolean"},
+                {"type": "integer", "exclusiveMinimum": 0}
+            ]
+        })
+    }
+}
+
 fn predefined_hook_schema(
     schema_gen: &mut schemars::SchemaGenerator,
     description: &str,

crates/prek/src/snapshots/prek__config__tests__read_config_with_nested_merge_keys.snap

@@ -27,7 +27,7 @@ Config {
                             always_run: None,
                             fail_fast: None,
                             pass_filenames: Some(
-                                false,
+                                None,
                             ),
                             description: None,
                             language_version: None,

crates/prek/src/snapshots/prek__config__tests__read_manifest.snap

@@ -30,7 +30,7 @@ Manifest {
                 always_run: None,
                 fail_fast: None,
                 pass_filenames: Some(
-                    false,
+                    None,
                 ),
                 description: Some(
                     "Automatically run 'uv pip compile' on your requirements",
@@ -72,7 +72,7 @@ Manifest {
                 always_run: None,
                 fail_fast: None,
                 pass_filenames: Some(
-                    false,
+                    None,
                 ),
                 description: Some(
                     "Automatically run 'uv lock' on your project dependencies",
@@ -117,7 +117,7 @@ Manifest {
                 always_run: None,
                 fail_fast: None,
                 pass_filenames: Some(
-                    false,
+                    None,
                 ),
                 description: Some(
                     "Automatically run 'uv export' on your project dependencies",

crates/prek/src/snapshots/prek__config__tests__read_yaml_config.snap

@@ -109,7 +109,7 @@ Config {
                             always_run: None,
                             fail_fast: None,
                             pass_filenames: Some(
-                                false,
+                                None,
                             ),
                             description: None,
                             language_version: None,
@@ -156,7 +156,7 @@ Config {
                             always_run: None,
                             fail_fast: None,
                             pass_filenames: Some(
-                                false,
+                                None,
                             ),
                             description: None,
                             language_version: None,

crates/prek/tests/run.rs

@@ -3105,3 +3105,44 @@ fn run_with_tree_object_as_ref() -> Result<()> {
 
     Ok(())
 }
+
+/// `pass_filenames: n` limits each invocation to at most n files.
+/// With n=1, each matched file gets its own invocation.
+#[test]
+fn pass_filenames_integer_limits_batch_size() -> Result<()> {
+    let context = TestContext::new();
+    context.init_project();
+
+    let cwd = context.work_dir();
+    // Use a script that errors if it receives more than one filename argument.
+    context.write_pre_commit_config(indoc::indoc! {r#"
+        repos:
+          - repo: local
+            hooks:
+              - id: one-at-a-time
+                name: one at a time
+                entry: python -c "import sys; args = sys.argv[1:]; sys.exit(0 if len(args) <= 1 else 1)"
+                language: system
+                pass_filenames: 1
+                require_serial: true
+                verbose: true
+    "#});
+
+    cwd.child("a.txt").write_str("a")?;
+    cwd.child("b.txt").write_str("b")?;
+    cwd.child("c.txt").write_str("c")?;
+    context.git_add(".");
+
+    cmd_snapshot!(context.filters(), context.run().arg("--all-files"), @r"
+    success: true
+    exit_code: 0
+    ----- stdout -----
+    one at a time............................................................Passed
+    - hook id: one-at-a-time
+    - duration: [TIME]
+
+    ----- stderr -----
+    ");
+
+    Ok(())
+}