feat: Support for Batch-Size in File Hooks

feat: Adds --hook:batch-size=N arguments to enable file batching
      Default = 1; 0 = All Files

docs: Updates README.md and sample-config.yaml for batch support

docs: Small update to Useful Hook Parameters

docs: Better placement of "--hook args can appear anywhere" messaging

chore: Run pre-commit hooks and fix shellcheck/shfmt warnings

Author: TekWizely

README.md

@@ -31,6 +31,13 @@ You can copy/paste the following snippet into your `.pre-commit-config.yaml` fil
     #
     #           --hook:env:NAME=VALUE
     #
+    # NOTE: You can set the number of files to process in a single command
+    #       invocation for file-based hooks using the following format:
+    #
+    #           --hook:batch-size=N
+    #
+    #       (N=0 will process all files in a single invocation)
+    #
     # NOTE: You can invoke hooks via 'go tool' using:
     #
     #           --hook:go-tool
@@ -211,6 +218,8 @@ See the [my-cmd](#my-cmd) hooks for more information.
 
 --------------------------
 ### Useful Hook Parameters
+Here are a few pre-commit parameters that may be useful when configuring hooks:
+
 ```
 -   id: hook-id
     args: [arg1, arg2, ..., '--'] # Pass options ('--' is optional)
@@ -245,7 +254,22 @@ The hook script will detect this argument and set the variable `NAME` to the val
 
 You can pass multiple  `--hook:env:` arguments.
 
-The arguments can appear anywhere in the `args:` list.
+#### Passing Batch Size To Hooks
+For file-based hooks, you can specify the number of files to include in a single command invocation.
+
+**NOTE:** By default, file-based hooks execute the command once for each staged file.
+
+This feature is enabled via support for a specially-formatted argument:
+
+* `--hook:batch-size=N`
+
+The hook script will detect this argument and use `N` as the batch size.
+
+* `N` must be an integer >= 0.
+* A value of `1` (the default) executes the command once for each file.
+* A value of `0` executes the command once for all files.
+* A value of `N > 1` executes the command once for every `N` files.
+  (note: the last execution may have < N files)
 
 #### Invoking Hooks Via go tool
 You can invoke hooks via `go tool` to ensure that a specific version of a tool is used (requires Go 1.24+).
@@ -388,6 +412,9 @@ By default, hooks ONLY run when matching file types (usually `*.go`) are staged.
 
 When configured to `"always_run"`, a hook is executed as if EVERY matching file were staged.
 
+#### Placement of --Hook: Arguments
+The special `--hook:` arguments listed above can appear anywhere in the `args:` list.
+
 #### Aliases / Names
 
 pre-commit supports the ability to assign both an `alias` and a `name` to a configured hook:

lib/cmd-files.bash

@@ -9,15 +9,24 @@
 prepare_file_hook_cmd "$@"
 
 error_code=0
-for file in "${FILES[@]}"; do
-	if [ "${error_on_output:-}" -eq 1 ]; then
-		output=$(/usr/bin/env "${ENV_VARS[@]}" "${cmd[@]}" "${OPTIONS[@]}" "${file}" 2>&1)
-		if [ -n "${output}" ]; then
-			printf "%s\n" "${output}"
+# If batch_size=0, process all files in one go
+if [ "${batch_size}" -eq 0 ]; then
+	batch_size=${#FILES[@]}
+fi
+
+# Handle empty FILES to avoid infinite loop if batch_size is also 0
+if [ ${#FILES[@]} -gt 0 ]; then
+	for ((i = 0; i < ${#FILES[@]}; i += batch_size)); do
+		batch=("${FILES[@]:i:batch_size}")
+		if [ "${error_on_output:-}" -eq 1 ]; then
+			output=$(/usr/bin/env "${ENV_VARS[@]}" "${cmd[@]}" "${OPTIONS[@]}" "${batch[@]}" 2>&1)
+			if [ -n "${output}" ]; then
+				printf "%s\n" "${output}"
+				error_code=1
+			fi
+		elif ! /usr/bin/env "${ENV_VARS[@]}" "${cmd[@]}" "${OPTIONS[@]}" "${batch[@]}"; then
 			error_code=1
 		fi
-	elif ! /usr/bin/env "${ENV_VARS[@]}" "${cmd[@]}" "${OPTIONS[@]}" "${file}"; then
-		error_code=1
-	fi
-done
+	done
+fi
 exit $error_code

lib/common.bash

@@ -7,6 +7,7 @@
 : "${ignore_pattern_array:=}"
 : "${ignore_file_pattern_array:=}"
 : "${ignore_dir_pattern_array:=}"
+: "${batch_size:=1}"
 ignore_dir_pattern_array+=("vendor")
 
 ##
@@ -214,6 +215,7 @@ function parse_file_hook_args {
 	# Positional order of saved arguments is preserved
 	#
 	local ENV_REGEX='^[a-zA-Z_][a-zA-Z0-9_]*=.*$'
+	local BATCH_SIZE_REGEX='^(0|[1-9][0-9]*)$'
 	ENV_VARS=()
 	local __ARGS=()
 	while [ $# -gt 0 ] && [ "$1" != "--" ]; do
@@ -228,6 +230,16 @@ function parse_file_hook_args {
 				fi
 				shift
 				;;
+			--hook:batch-size=*)
+				local batch_size_arg="${1#--hook:batch-size=}"
+				if [[ "${batch_size_arg}" =~ ${BATCH_SIZE_REGEX} ]]; then
+					batch_size="${batch_size_arg}"
+				else
+					printf "ERROR: Invalid hook:batch-size value: '%s'\n" "${batch_size_arg}" >&2
+					exit 1
+				fi
+				shift
+				;;
 			--hook:ignore-pattern=*)
 				local ignore_pattern="${1#--hook:ignore-pattern=}"
 				if [[ -n "${ignore_pattern}" ]]; then

sample-config.yaml

@@ -74,6 +74,14 @@ repos:
     #
     #           --hook:env:NAME=VALUE
     #
+    # Passing Batch Size to Hooks:
+    #  You can set the number of files to process in a single command
+    #  invocation for file-based hooks using the following format:
+    #
+    #           --hook:batch-size=N
+    #
+    #       (N=0 will process all files in a single invocation)
+    #
     # NOTE: You can invoke hooks via 'go tool' using:
     #
     #           --hook:go-tool