Add cookbook page for enabling Git 2.54 config-based global hooks (#2061)

Adds a Cookbook docs page with a first recipe for enabling Git 2.54
config-based global hooks with `prek hook-impl`.

Closes #58

docs/cookbook.md

@@ -0,0 +1,54 @@
+# Cookbook
+
+Short recipes for setup patterns that go beyond the default project-local workflow.
+
+## Enable a Global Hook with Git Config
+
+Git 2.54 introduced [config-based hooks](https://github.blog/open-source/git/highlights-from-git-2-54/#h-config-based-hooks), which let Git run hooks from config instead of hook scripts.
+This is useful when you want a personal `prek` hook that works across repositories.
+
+Choose the Git hook event you want to run on, for example `pre-commit`, then register a global config-based hook:
+
+```bash
+git config --global hook.prek-pre-commit.event pre-commit
+git config --global hook.prek-pre-commit.command 'prek hook-impl --hook-type pre-commit --skip-on-missing-config --'
+```
+
+The config has three moving parts:
+
+- `hook.<friendly-name>.event`: the Git hook event to listen for, such as `pre-commit`, `pre-push`, or `commit-msg`.
+- `hook.<friendly-name>.command`: the command Git runs for that event.
+- `<friendly-name>`: a user-defined name for this configured hook. Keep it unique in your Git config.
+
+Keep `--skip-on-missing-config` in the command so repositories without a `prek.toml` or `.pre-commit-config.yaml` do not fail ordinary Git operations.
+Keep the trailing `--` so Git-provided hook arguments, such as a `commit-msg` filename or `pre-push` remote name and URL, are forwarded to `prek hook-impl` instead of being parsed as hook selectors.
+
+To configure a different event, replace both occurrences of `pre-commit`:
+
+```bash
+git config --global hook.<friendly-name>.event <event>
+git config --global hook.<friendly-name>.command 'prek hook-impl --hook-type <event> --skip-on-missing-config --'
+```
+
+By default, `prek hook-impl` discovers the current repository's config.
+If you want one global hook config to run in every repository, pass that config explicitly:
+
+```bash
+git config --global hook.<friendly-name>.command 'prek hook-impl --hook-type <event> --config <config-file> --'
+```
+
+For example, a global config file at `~/.config/prek/global-hooks.toml` can run gitleaks in every repository:
+
+```toml
+[[repos]]
+repo = "https://github.com/gitleaks/gitleaks"
+rev = "v8.24.2"
+hooks = [{ id = "gitleaks" }]
+```
+
+Then point the global Git hook at that config:
+
+```bash
+git config --global hook.gitleaks.event pre-commit
+git config --global hook.gitleaks.command 'prek hook-impl --hook-type pre-commit --config ~/.config/prek/global-hooks.toml --'
+```

docs/index.md

@@ -22,6 +22,7 @@
 - New to `prek`: start with [Installation](installation.md), then follow the [Quickstart](quickstart.md).
 - Already set up: use [Common Workflows](usage.md) for the commands you run day to day.
 - Writing config: read [Configuration](configuration.md), then use the [Configuration Reference](reference/configuration.md) for exact keys.
+- Looking for setup patterns: browse the [Cookbook](cookbook.md).
 - Working in a monorepo: see [Workspace Mode](workspace.md).
 - Looking for flags or environment variables: use the [CLI Reference](reference/cli.md) and [Environment Variable Reference](reference/environment-variables.md).
 

mkdocs.yml

@@ -84,6 +84,7 @@ plugins:
           - languages.md
           - builtin.md
           - integrations.md
+          - cookbook.md
           - authoring-hooks.md
         Reference:
           - reference/cli.md
@@ -110,6 +111,7 @@ nav:
     - Language Support: languages.md
     - Built-in Hooks: builtin.md
     - Integrations: integrations.md
+    - Cookbook: cookbook.md
     - Authoring Hooks: authoring-hooks.md
   - Reference:
     - CLI Reference: reference/cli.md

skills/prek/SKILL.md

@@ -21,6 +21,7 @@ Per that file, prefer explicit markdown docs when you need details:
 - [Installation](https://prek.j178.dev/installation/index.md)
 - [Quickstart](https://prek.j178.dev/quickstart/index.md)
 - [Common Workflows](https://prek.j178.dev/usage/index.md)
+- [Cookbook](https://prek.j178.dev/cookbook/index.md)
 - [Configuration](https://prek.j178.dev/configuration/index.md)
 - [Workspace Mode](https://prek.j178.dev/workspace/index.md)
 - [Language Support](https://prek.j178.dev/languages/index.md)