Proposal: Hook `groups` + `prek run --group/--no-group`

[CarliJoy]

Motivation

There is a nice service for pre-commit called https://pre-commit.ci/.

I do not think that prek should copy or reimplement this feature.

However, it would be beneficial if prek could be used more naturally within a CI/CD pipeline, as this would reduce duplicated configuration.

Current Behaviour

At the moment, I can already run:

prek run --all-files

within my CI/CD script.
By default, this runs hooks that either have no stages definition (defaulting to all stages) or explicitly include the pre-commit stage.

For my use case, I would like to skip a specific hook within CI/CD because it is already checked by another job.
pre-commit.ci supports this via ci.skip.

Currently, I can work around this by running:

prek run --all-files --hook-type manual

in CI and configuring hooks like this:

repos:
  - repo: 'git@something'
    rev: '1.6.1'
    hooks:
      - id: 'lint'
        stages: ['pre-push', 'manual']
      - id: 'format'
        stages: ['pre-commit', 'manual']
      - id: 'test'
        stages: ['pre-push']

However, for someone reading this configuration and knowing it is executed in CI/CD, this is confusing.
The manual stage semantically suggests the opposite of CI/CD.

Click to view old suggestion

Suggested Behaviour (Old)

Therefore, I suggest adding a dedicated ci hook stage for this use case.

The intention would then be clear when running:

prek run --hook-type ci

Example configuration:

repos:
  - repo: 'git@something'
    rev: '1.6.1'
    hooks:
      - id: 'lint'
        stages: ['pre-push', 'ci']
      - id: 'format'
        stages: ['pre-commit', 'ci']
      - id: 'test'
        stages: ['pre-commit']

This is a small change, but it would encourage and simplify the use of prek in CI/CD environments.

Suggested Behaviour (new)

As @pygarap pointed out, a good solution for this problem would be the introduction of "groups".

Example Configuration

repos:
  - repo: 'git@something'
    rev: '1.6.1'
    hooks:
      - id: 'lint'
        groups: ['ci']
        stages: ['pre-push']
      - id: 'format'
        groups: ['ci']
      - id: 'test'
        stages: ['pre-push']

Now we could just run prek run --all-files --group ci

Group should be repeatable:
prek run --all-files --group ci --group lint --group test

It might be nice to add a --exclude-group:
prek run --all-files --exclude-group format

To be noted --group (incl. --exlcude-group and --hook-type should be mutually exclusive.
Once a group is selected hook stages are ignored for the selection which hook to run.

[pygarap]

@CarliJoy

I get what you mean, but I do not think the “manual” stage semantically suggests the opposite of CI.

In CI, you always explicitly invoke prek run, and you do not install or rely on Git hooks. By definition, that is “manual” execution in the same sense as “run it explicitly via the CLI”, even if the environment is automated.

Also, adding a dedicated CI stage solves only one specific naming preference. Other users may reasonably want different stages for different environments or workflows, and we could end up with a growing list of special-purpose stages.

It sounds like what you actually want is a way to group hooks into user-defined categories, and then run (or skip) hooks by those groups. For example, define any number of groups with arbitrary names (like ci, fast, slow, lint-only, no-format, etc.), assign hooks to one or more groups, and then run:
• only hooks in a given group (or set of groups), and/or
• exclude hooks in a given group

That would cover your CI use case cleanly (without overloading “manual”), while staying flexible for everyone else.

So if I understand you correctly, your feature request should be a new way to group hooks into user-defined categories, and it should not be related to the hook's stages.

[CarliJoy]

@pygarap

I understand your concern about adding ci as explicit hook stage. I like the sound of the idea of hook groups but can't picture it.

Could you provide examples how a configuration would look like and which command would be executed in ci?

[pygarap]

@CarliJoy

Proposed config shape

Add a groups field per hook (similar to stages, but user-defined and not tied to Git hook semantics):

repos:
  - repo: 'git@something'
    rev: '1.6.1'
    hooks:
      - id: 'lint'
        groups: ['ci']
      - id: 'format'
        groups: ['ci']
      - id: 'test'

How CI would run it

In CI you would run only the ci group:

prek run --all-files --group ci

Optionally, if you want multiple groups:

prek run --all-files --group ci --group lint --group test

And if you want an exclude form (useful for “run everything except formatting”):

prek run --all-files --exclude-group format

Why this helps vs adding a ci stage

• Keeps stages for Git hook contexts (pre-commit, pre-push, etc.).
• Avoids adding more one-off stages (ci, docker, release, nightly, etc.).
• Solves the real need: select a subset of hooks for a given job without redefining stages.

If hooks should run both locally and in CI, keep stages as-is (or omit them) and use groups only for CI selection.

[CarliJoy]

I love the idea.

Just one note: I would add that once any group command is used --hook-type is set to Any (which is not a option at the moment).

I will edit my original comment.

[j178]

Here’s a more formal proposal based on the earlier comments.

Proposal: Hook groups + prek run --group/--no-group

Add an optional hook-level field groups to allow tagging hooks with arbitrary group names, and add CLI filters to run (or exclude) hooks by those groups.

Config change

• New key: groups
• Type: Vec<String> / YAML list of strings
• Default: empty ([])
• Values: any string (no enforced vocabulary)

Example:

- id: ruff
  groups: ["lint", "python"]

CLI change

• prek run --group <name> (repeatable): include filter — run only hooks whose groups contains at least one of the specified names.
• prek run --no-group <name> (repeatable): exclude filter — do not run hooks whose groups contains any of the specified names.
• If both are provided, exclusion wins (i.e., select by --group first, then remove anything matched by --no-group).

Semantics / edge cases

• Hooks with groups: [] are “ungrouped”.
• If no --group is provided, behavior is unchanged (no filtering; all selected hooks run).
• If --group is provided, ungrouped hooks do not match and therefore won’t run (unless we later add a dedicated “ungrouped” selector; out of scope for now).

This is a new feature proposal only; I’m intentionally deferring implementation until there’s more feedback/consensus (e.g., when the issue reaches 10 👍).

[CarliJoy]

Thanks, Jo.

One additional clarification might be worth adding to the specification:

When using --group, --hook-type should be ignored.

Accordingly, the prek run help text could state something along the lines of:

Hooks can be selected either by group or by hook type, but not both.

Without this rule, the intended use case becomes harder to motivate. If hooks are defined for different Git hook stages, each of them must include manual to make grouping usable at all. In practice, this then requires always running:

prek run --group <foo> --hook-type manual

Ignoring --hook-type when --group is specified avoids this redundancy and keeps group-based execution straightforward.

[pygarap]

@CarliJoy That makes sense, but one key detail is that we are talking specifically about prek run. In practice, stages and --hook-type are almost entirely relevant to prek install (which git hook scripts get installed), not to prek run.

Also, almost all hooks do not define stages in their .pre-commit-hooks.yaml, so stage selection is usually controlled by the user in .pre-commit-config.yaml. And when a hook does not specify stages, default_stages defaults to all stages, so hooks are eligible to run in any stage anyway. Because of that, --hook-type often is not a meaningful filter for most hooks in prek run.

[pygarap]

@CarliJoy @j178

I also suggest adding --output-format=grouped to prek run, so the hooks output is grouped and sorted according to the configured groups.