Skip to content

Commit da457c5

Browse files
authored
Document hook stage file input (#2147)
Closes #2144
1 parent 0fa2929 commit da457c5

2 files changed

Lines changed: 36 additions & 0 deletions

File tree

‎docs/authoring-hooks.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -96,6 +96,9 @@ configuration. If neither is set, `prek` falls back to the top-level
9696
The `manual` stage is special: it never runs automatically and is only executed
9797
when a user explicitly runs `prek run --hook-stage manual <hook-id>`.
9898

99+
For what each stage means and whether it operates on repository files, see
100+
[Supported Git Hook Stages](reference/configuration.md#supported-git-hook-stages).
101+
99102
Example:
100103

101104
```yaml

‎docs/reference/configuration.md‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -266,6 +266,8 @@ Allowed values:
266266
- `pre-rebase`
267267
- `prepare-commit-msg`
268268

269+
See [Supported Git Hook Stages](#supported-git-hook-stages) for what each value means.
270+
269271
### `default_install_hook_types`
270272

271273
Default Git shim name(s) installed by [`prek install`](cli.md#prek-install) when you don’t pass `--hook-type`.
@@ -603,6 +605,32 @@ For `repo: local`, the hook entry is a full definition and must include:
603605
For `repo: builtin` and `repo: meta`, the hook entry must include `id`.
604606
You can optionally provide `name` and normal hook options (filters, [`stages`](#stages), etc), but not `entry`.
605607

608+
## Supported Git Hook Stages
609+
610+
`prek` follows upstream [`pre-commit` behavior](https://pre-commit.com/#supported-git-hooks) for Git hook stages. The
611+
[`stages`](#stages) option controls which hooks are eligible to run; the selected
612+
stage controls what input the hook receives.
613+
614+
Stages with no repository file input do not have candidate filenames for
615+
[`files`](#hook-files-exclude), [`exclude`](#hook-files-exclude),
616+
[`types`](#hook-types), [`types_or`](#hook-types), or
617+
[`exclude_types`](#hook-types). Hooks in those stages need
618+
[`always_run: true`](#always_run) to run automatically.
619+
620+
| Stage | When it runs | Hook input |
621+
| -- | -- | -- |
622+
| `manual` | Only when selected explicitly, for example with `prek run --hook-stage manual`. | Repository file paths selected by the `prek run` file mode. |
623+
| `commit-msg` | During commit message validation. | Git's commit message file, not repository file paths. |
624+
| `post-checkout` | After a checkout has occurred. | No repository file input. |
625+
| `post-commit` | After a commit has already succeeded. | No repository file input. |
626+
| `post-merge` | After a successful merge. | No repository file input. |
627+
| `post-rewrite` | After a command rewrites history, such as amend or rebase. | No repository file input. |
628+
| `pre-commit` | Before a commit is finalized. | Repository file paths from the staged contents; unstaged changes are temporarily stashed while hooks run. |
629+
| `pre-merge-commit` | After a merge succeeds but before the merge commit is created. | Repository file paths from the staged merge result. |
630+
| `pre-push` | During `git push`. | Repository file paths changed in the push range. |
631+
| `pre-rebase` | Before a rebase starts. | No repository file input. |
632+
| `prepare-commit-msg` | Before the commit message editor opens or before the commit message is finalized. | Git's commit message file, not repository file paths. |
633+
606634
## Common hook options
607635

608636
These keys can appear on hooks (remote/local/builtin/meta), subject to the restrictions above.
@@ -835,6 +863,8 @@ As a `prek` extension, you can also specify globs using `glob` or a glob list.
835863

836864
See [Top-level `files`](#top-level-files) and [Top-level `exclude`](#top-level-exclude) for syntax notes and examples.
837865

866+
<a id="hook-types"></a>
867+
838868
### `types` / `types_or` / `exclude_types`
839869

840870
File-type filters based on [`identify`](https://pre-commit.com/#filtering-files-with-types) tags.
@@ -1001,6 +1031,9 @@ Allowed values:
10011031
- `pre-rebase`
10021032
- `prepare-commit-msg`
10031033

1034+
For behavior of each stage and whether it operates on repository files, see
1035+
[Supported Git Hook Stages](#supported-git-hook-stages).
1036+
10041037
When you run [`prek run --hook-stage <stage>`](cli.md#prek-run), only hooks configured for that stage are considered.
10051038

10061039
### `groups`

0 commit comments

Comments
 (0)