Parallel Git hooks

Run custom Git hooks in parallel using Nushell, designed for integration with devenv.

Quick Start

Important

This quick start assumes you already have devenv and Nushell set up.

• All hooks run in parallel, so ensure that commands do not conflict with one another.
• All hooks will run to completion, even if one or more fail.
• A hook will block if there are any unstaged changes that match the filter, or if the command returns a non-zero exit code.
• Optionally, hooks can also include untracked files by enabling the includeUntracked option.

Usage

1. Add as a devenv input

In your devenv.yaml:

inputs:
  # Other inputs…

  parallel-git-hooks:
    url: github:frederikstroem/parallel-git-hooks

2. Import and configure the module

In your devenv.nix:

{ pkgs, lib, config, inputs, ... }:

{
  # Import the parallel-git-hooks module from the flake input
  imports = [
    inputs.parallel-git-hooks.devenvModule
  ];

  # Define the commands used in the hooks
  scripts = {
    format-docs = {
      exec = ''
        # Your formatting logic
        echo "Formatting docs..."
      '';
    };

    gen-fig = {
      exec = ''
        # Your figure generation logic
        echo "Generating figures..."
      '';
    };
  };

  # Enable and configure parallel Git hooks
  parallel-git-hooks = {
    enable = true;
    hooks = [
      {
        name = "Format docs";
        cmd = "format-docs";
        fileFilter = "^docs/.*\\.md$";
      }
      {
        name = "Generate figures";
        cmd = "gen-fig";
        fileFilter = "^figures/.*\\.(svg|pdf)$";
        # Also include untracked files matching the filter
        includeUntracked = true;
      }
    ];
  };
}

Module options

• parallel-git-hooks.enable - Enable parallel Git hooks (default: false)
• parallel-git-hooks.logLevel - Log level for hook execution output (default: "INFO")
  • Allowed values: "DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"
  • Use "DEBUG" for detailed troubleshooting information
• parallel-git-hooks.hooks - List of hooks to run in parallel
  • name - Display name for the hook
  • cmd - Command to execute (can be a devenv script or any shell command)
  • fileFilter - Regex pattern to match files for unstaged change detection
  • includeUntracked - Whether to also include untracked files matching the filter (default: false)
    • When enabled, the commit will be blocked if there are any untracked files matching the fileFilter pattern
    • Useful for ensuring generated files are committed before allowing the commit to proceed

Debugging

The logLevel option controls the verbosity of the hook execution output, using logging levels defined by Nushell's standard library:

• DEBUG - Most verbose; shows detailed execution information, file matching details, and internal state
• INFO - Default level; shows general information about hook execution
• WARNING - Shows only warnings and errors
• ERROR - Shows only errors and critical messages
• CRITICAL - Shows only critical messages

To enable debug logging for troubleshooting:

parallel-git-hooks = {
  enable = true;
  logLevel = "DEBUG";
  hooks = [ /* ... */ ];
};

This sets the NU_LOG_LEVEL environment variable internally, controlling the output from log commands used by the hook runner script.

Note

The NU_LOG_LEVEL environment variable will propagate to all invoked hook commands. If your hook command is a Nushell script that uses the log module, it will also inherit the same log level.