Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 8 additions & 2 deletions crates/prek/src/cli/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -683,13 +683,19 @@ pub(crate) struct RunArgs {

/// Run hooks belonging to the specified group.
///
/// Can be specified multiple times.
/// Can be specified multiple times; a hook may match any specified group.
/// When combined with `--require-group`, both filters must match.
#[arg(long = "group", value_name = "GROUP")]
pub(crate) groups: Vec<String>,

/// Run hooks belonging to every specified group.
///
/// Can be specified multiple times. Composes with `--group` and `--no-group`.
/// Can be specified multiple times; a hook must match every specified group.
/// When combined with `--group`, it must also match at least one `--group`.
/// `--no-group` excludes matching hooks regardless of argument order.
///
/// For example, `--require-group fast --group format --group lint-only`
/// selects hooks in `fast` and either `format` or `lint-only`.
#[arg(long = "require-group", value_name = "GROUP")]
pub(crate) required_groups: Vec<String>,

Expand Down
27 changes: 27 additions & 0 deletions crates/prek/tests/run.rs
Original file line number Diff line number Diff line change
Expand Up @@ -986,6 +986,33 @@ fn run_required_groups_intersect_and_compose_with_other_group_filters() {
"
);

cmd_snapshot!(
context.filters(),
context
.run()
.arg("--all-files")
.arg("--group")
.arg("ci")
.arg("--require-group")
.arg("slow")
.arg("--no-group")
.arg("local")
.arg("--group")
.arg("lint")
.arg("--require-group")
.arg("format")
.arg("--no-group")
.arg("fast"),
@r"
success: true
exit_code: 0
----- stdout -----
Black....................................................................Passed

----- stderr -----
"
);

cmd_snapshot!(
context.filters(),
context
Expand Down
26 changes: 26 additions & 0 deletions docs/proposals/hook-groups.md
Original file line number Diff line number Diff line change
Expand Up @@ -111,6 +111,16 @@ The three options compose independently of argument order, and exclusion wins:
2. Keep only hooks matching every `--require-group` value, if any were provided.
3. Remove hooks matching `--no-group`, if any `--no-group` values were provided.

Equivalently, a hook must satisfy:

```text
(any --group value matches, if specified)
AND
(every --require-group value matches)
AND
(no --no-group value matches)
```

Examples:

```bash
Expand All @@ -122,6 +132,22 @@ prek run --all-files --group ci --require-group lint --no-group slow
prek run --all-files --group ci --stage pre-push
```

For example, consider these hook groups:

| Hook | Groups |
| -- | -- |
| `ty` | `lint-only`, `fast`, `local` |
| `ruff-format` | `format`, `fast`, `local` |
| `mypy` | `lint-only`, `slow`, `ci` |
| `black` | `format`, `slow`, `ci` |

```bash
prek run --all-files --require-group fast --group format --group lint-only
```

This represents `fast AND (format OR lint-only)`, so it selects exactly `ty`
and `ruff-format`. Reordering the options does not change the selection.

## Selection Model

Group filtering composes with existing project and hook selectors. The effective
Expand Down
5 changes: 3 additions & 2 deletions docs/reference/cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -233,7 +233,7 @@ prek run [OPTIONS] [HOOK|PROJECT]...
</dd><dt id="prek-run--glob"><a href="#prek-run--glob"><code>--glob</code></a> <i>pattern</i></dt><dd><p>Run hooks on tracked files matching the specified glob pattern.</p>
<p>Patterns are matched against paths relative to the current working directory after applying <code>--cd</code>. Quote patterns to prevent shell expansion. This option can be repeated and combined with <code>--files</code> and <code>--directory</code>.</p>
</dd><dt id="prek-run--group"><a href="#prek-run--group"><code>--group</code></a> <i>group</i></dt><dd><p>Run hooks belonging to the specified group.</p>
<p>Can be specified multiple times.</p>
<p>Can be specified multiple times; a hook may match any specified group. When combined with <code>--require-group</code>, both filters must match.</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--last-commit"><a href="#prek-run--last-commit"><code>--last-commit</code></a></dt><dd><p>Run hooks against the last commit. Equivalent to <code>--from-ref HEAD~1 --to-ref HEAD</code></p>
</dd><dt id="prek-run--log-file"><a href="#prek-run--log-file"><code>--log-file</code></a> <i>log-file</i></dt><dd><p>Write trace logs to the specified file. If not specified, trace logs will be written to <code>$PREK_HOME/prek.log</code></p>
Expand All @@ -245,7 +245,8 @@ prek run [OPTIONS] [HOOK|PROJECT]...
<p>Repeating this option, e.g., <code>-qq</code>, will enable a silent mode in which prek will write no output to stdout.</p>
<p>May also be set with the <code>PREK_QUIET</code> environment variable.</p></dd><dt id="prek-run--refresh"><a href="#prek-run--refresh"><code>--refresh</code></a></dt><dd><p>Refresh all cached data</p>
</dd><dt id="prek-run--require-group"><a href="#prek-run--require-group"><code>--require-group</code></a> <i>group</i></dt><dd><p>Run hooks belonging to every specified group.</p>
<p>Can be specified multiple times. Composes with <code>--group</code> and <code>--no-group</code>.</p>
<p>Can be specified multiple times; a hook must match every specified group. When combined with <code>--group</code>, it must also match at least one <code>--group</code>. <code>--no-group</code> excludes matching hooks regardless of argument order.</p>
<p>For example, <code>--require-group fast --group format --group lint-only</code> selects hooks in <code>fast</code> and either <code>format</code> or <code>lint-only</code>.</p>
</dd><dt id="prek-run--show-diff-on-failure"><a href="#prek-run--show-diff-on-failure"><code>--show-diff-on-failure</code></a></dt><dd><p>When hooks fail, run <code>git diff</code> directly afterward</p>
</dd><dt id="prek-run--skip"><a href="#prek-run--skip"><code>--skip</code></a> <i>hook|project</i></dt><dd><p>Skip the specified hooks or projects.</p>
<p>Supports flexible selector syntax:</p>
Expand Down
16 changes: 16 additions & 0 deletions docs/reference/configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -1223,6 +1223,22 @@ Repeated `--group` values use union semantics, while repeated
`--require-group` values use intersection semantics. When combined, a hook must
match at least one `--group`, every `--require-group`, and no `--no-group`.

For example, consider these hook groups:

| Hook | Groups |
| -- | -- |
| `ty` | `lint-only`, `fast`, `local` |
| `ruff-format` | `format`, `fast`, `local` |
| `mypy` | `lint-only`, `slow`, `ci` |
| `black` | `format`, `slow`, `ci` |

```bash
prek run --all-files --require-group fast --group format --group lint-only
```

This represents `fast AND (format OR lint-only)`, so it selects exactly `ty`
and `ruff-format`. Reordering the options does not change the selection.

When any group selector is used without `--stage`, group filtering is not
constrained by hook stage. `prek run` collects normal file input for the manual
command and runs every matching hook that can use that input. Hooks configured
Expand Down
Loading