diff --git a/plugins/git/.apm/skills/pc-run/README.md b/plugins/git/.apm/skills/pc-run/README.md index 7113b56..be4b26c 100644 --- a/plugins/git/.apm/skills/pc-run/README.md +++ b/plugins/git/.apm/skills/pc-run/README.md @@ -24,6 +24,9 @@ Common invocations: | File | Purpose | |------|---------| | `SKILL.md` | Skill instructions for agents | -| `references/failure-patterns.md` | Hook failure causes and concrete fix suggestions | +| `references/install.md` | The install flow — loaded when the user asks to install or set up hooks | +| `references/autoupdate.md` | The autoupdate flow — loaded when the user asks to bump hook revs | +| `references/clean.md` | The clean flow — loaded when the user asks to wipe the cache or rebuild environments | +| `references/failure-patterns.md` | Hook failure causes and concrete fix suggestions — loaded when a hook fails or never fires | | `references/sources.md` | Provenance: research sources that informed this skill | | `references/README.md` | Directory index for references/ | diff --git a/plugins/git/.apm/skills/pc-run/SKILL.md b/plugins/git/.apm/skills/pc-run/SKILL.md index d603638..e1da3a3 100644 --- a/plugins/git/.apm/skills/pc-run/SKILL.md +++ b/plugins/git/.apm/skills/pc-run/SKILL.md @@ -1,13 +1,9 @@ --- name: pc-run description: > - Use when the user wants to run pre-commit hooks, install git hooks, update - hook versions, or maintain the pre-commit cache. Triggers on: "run - pre-commit", "run all hooks", "check everything passes", "install hooks", - "wire hooks into git", "update hook versions", "autoupdate", "bump revs", - "clean the cache", "rebuild environments", "gc", "why is my hook failing", - "hooks aren't running". Do not use for creating or editing - `.pre-commit-config.yaml` — use `pc-author` for that. + Use when the user wants to run pre-commit hooks, wire them into git, bump hook + revs, maintain the cache, or diagnose why a hook fails or never fires. Not + creating or editing the pre-commit config -> `pc-author`. compatibility: Requires pre-commit installed and available on PATH. @@ -22,102 +18,34 @@ allowed-tools: Bash Read ## Gotchas -- Hooks not running on `git commit` almost always means `pre-commit install` was never run in this clone. Git hooks are per-clone — they are not committed to the repo. -- When a hook modifies files (e.g. `trailing-whitespace`, `end-of-file-fixer`), the commit is blocked intentionally — the staged version is stale. The fix is `git add -u && git commit`. Do NOT call `pre-commit install -f` here; that is for overwriting existing hooks, not re-staging. -- `pre-commit autoupdate` modifies `.pre-commit-config.yaml` in-place. Re-read the file after calling it to show the user the updated `rev` values. -- The `SKIP` env var requires exact hook `id` values, comma-separated, no spaces: `SKIP=check-yaml,gitleaks git commit -m "msg"`. A space after the comma silently skips nothing. -- Never use `git commit --no-verify` (or `-n`) to bypass a failing hook. Hooks are the automated QA gate; bypassing them breaks the pipeline. Diagnose and fix the failure instead — see the hook-specific guidance below and in `references/failure-patterns.md`. -- A stages mismatch — hook stage not installed — means the hook was added to the config but `pre-commit install` was not re-run with the correct `-t` flags. Hooks in stages not listed under `default_install_hook_types` will never fire. +- The `SKIP` env var takes exact hook `id` values, comma-separated with no spaces: `SKIP=check-yaml,gitleaks git commit -m "msg"`. A space after a comma silently skips nothing instead of erroring. +- Never bypass a failing hook with `git commit --no-verify` (or `-n`). Hooks are the automated QA gate, so a bypassed commit pushes the failure downstream where it costs more — diagnose it instead. ## Route -Determine intent from the user's request, then execute the matching operation: +Determine intent from the user's request, then execute the matching operation. Where the matching row names a `references/` file, read that one file and no other — each flow file is self-contained. | User intent | Operation | |---|---| | "run", "check", "verify", "test hooks" | `pre-commit run --all-files` (default) | | "staged", "simulate commit" | `pre-commit run` (staged files only) | | "CI", "changed files only", "diff range" | `pre-commit run --from-ref --to-ref ` — prefer this over `--all-files` on large repos | -| "install", "set up hooks", "wire into git" | `pre-commit install` — see Install | -| "pre-create environments", "install-hooks", "warm cache" | `pre-commit install-hooks` — see Install | -| "remove hooks", "uninstall", "tear down pre-commit" | `pre-commit uninstall` | -| "autoupdate", "update versions", "bump revs" | `pre-commit autoupdate` | -| "gc", "garbage collect" | `pre-commit gc` | -| "clean", "wipe cache", "rebuild from scratch" | `pre-commit clean` — see Clean | +| "install", "set up hooks", "wire into git" | `pre-commit install` — read `references/install.md` | +| "pre-create environments", "warm cache" | `pre-commit install-hooks` — builds every hook environment without running a hook | +| "remove hooks", "uninstall", "tear down" | `pre-commit uninstall` — removes pre-commit from `.git/hooks/` | +| "autoupdate", "update versions", "bump revs" | `pre-commit autoupdate` — read `references/autoupdate.md` | +| "gc", "garbage collect" | `pre-commit gc` — drops unused cached environments only, safe at any time | +| "clean", "wipe cache", "rebuild from scratch" | `pre-commit clean` — read `references/clean.md` | +| "hooks aren't running", "hook never fires", "why did a hook fail" | Diagnose — read `references/failure-patterns.md` | If the intent is ambiguous, default to `pre-commit run --all-files`. ## Run -Default: `pre-commit run --all-files`. Never silently run staged-only. +Default to `pre-commit run --all-files`; never silently narrow to staged files. Run `pre-commit run` (staged only) or `pre-commit run ` (one named hook) when the user asks for it. -```bash -pre-commit run --all-files -``` +When hooks fail: -**When hooks fail**, read the output and: -1. Identify which hook failed and the specific cause. Be concrete: "gitleaks blocked `config.json` (high-entropy string on line 12)", not just "gitleaks failed". -2. Suggest a concrete next step. Common patterns are in `references/failure-patterns.md`. -3. Do NOT auto-fix code files. Do NOT modify `.pre-commit-config.yaml`. Those are the user's or `pc-author`'s responsibility. - -If the user asks to run only staged files: `pre-commit run` (no `--all-files`). -If the user names a specific hook: `pre-commit run `. - -## Install - -Only run when the user explicitly asks to install or set up hooks. - -Before running, check for existing hook files: - -```bash -ls .git/hooks/ -``` - -If any hook files exist (e.g. a hand-written `pre-commit`), `pre-commit install` does NOT refuse or error — it defaults to migration mode, which runs the existing hook and pre-commit's hooks both. Only `-f` replaces the existing hook file outright, and that replacement is not reversible via `pre-commit uninstall` — uninstall only removes pre-commit from `.git/hooks/`, it does not restore whatever hand-written hook `-f` overwrote. If files are present, tell the user: "Existing hook files found at `.git/hooks/`. Plain `pre-commit install` will run both; `pre-commit install -f` will overwrite them permanently instead. Proceed with plain install, or overwrite?" Wait for confirmation before using `-f`. - -```bash -pre-commit install -``` - -Re-run with `-t` flags when `default_install_hook_types` was changed or when hooks in non-default stages aren't firing: - -```bash -pre-commit install -t pre-commit -t pre-push -t commit-msg -``` - -To pre-create all hook environments without running hooks (useful for CI warm-up or first-time setup): - -```bash -pre-commit install-hooks -``` - -To remove pre-commit from `.git/hooks/` entirely: - -```bash -pre-commit uninstall -``` - -## Autoupdate - -```bash -pre-commit autoupdate -``` - -After it completes, read `.pre-commit-config.yaml` and report which `rev` values changed. If the user wants to pin to exact SHAs (for reproducibility): `pre-commit autoupdate --freeze`. - -## Clean and GC - -**`gc`** — removes only unused cached environments. Safe to run at any time: -```bash -pre-commit gc -``` - -**`clean`** — wipes the entire cache at `~/.cache/pre-commit`. All hook environments will be re-downloaded on next run. Require explicit confirmation before running: - -> "This will wipe the entire pre-commit cache. All hook environments will be re-downloaded on next run. Proceed?" - -Wait for the user to say yes before executing: - -```bash -pre-commit clean -``` +1. Name the hook and the specific cause. Be concrete — "gitleaks blocked `config.json` (high-entropy string on line 12)", not "gitleaks failed". +2. Suggest one concrete next step. If the cause is not obvious from the output, read `references/failure-patterns.md`. +3. Do not auto-fix code files, and do not edit `.pre-commit-config.yaml` — those belong to the user or to `pc-author`. diff --git a/plugins/git/.apm/skills/pc-run/references/README.md b/plugins/git/.apm/skills/pc-run/references/README.md index 4340626..51290f8 100644 --- a/plugins/git/.apm/skills/pc-run/references/README.md +++ b/plugins/git/.apm/skills/pc-run/references/README.md @@ -10,5 +10,8 @@ source_keys: | File | Purpose | |---|---| -| `failure-patterns.md` | Hook failure causes and concrete fix suggestions — loaded when hooks fail | +| `install.md` | The install flow — read when the user asks to install or set up hooks | +| `autoupdate.md` | The autoupdate flow — read when the user asks to bump hook revs | +| `clean.md` | The clean flow — read when the user asks to wipe the cache or rebuild environments | +| `failure-patterns.md` | Hook failure causes and concrete fix suggestions — read when a hook fails or never fires | | `sources.md` | Provenance: research sources that informed this skill | diff --git a/plugins/git/.apm/skills/pc-run/references/autoupdate.md b/plugins/git/.apm/skills/pc-run/references/autoupdate.md new file mode 100644 index 0000000..b222994 --- /dev/null +++ b/plugins/git/.apm/skills/pc-run/references/autoupdate.md @@ -0,0 +1,17 @@ +--- +source_keys: + - context7-pre-commit-com + - pre-commit-com +--- + +# Bumping hook revs with `autoupdate` + +Reached from `SKILL.md`'s Route table when the user asks to update hook versions or bump revs. Self-contained. + +```bash +pre-commit autoupdate +``` + +This rewrites `.pre-commit-config.yaml` in place, so re-read the file afterwards and report which `rev` values changed. It is the one operation in this skill that writes that file, and the exception is deliberate: the rewrite is pre-commit's own, resolved against the hook repos, not a hand edit — which is why `pc-author` hands rev bumps here rather than making them itself. + +Add `--freeze` when the user wants exact SHAs pinned for reproducibility. diff --git a/plugins/git/.apm/skills/pc-run/references/clean.md b/plugins/git/.apm/skills/pc-run/references/clean.md new file mode 100644 index 0000000..0ab452b --- /dev/null +++ b/plugins/git/.apm/skills/pc-run/references/clean.md @@ -0,0 +1,21 @@ +--- +source_keys: + - context7-pre-commit-com + - pre-commit-com +--- + +# Wiping the pre-commit cache + +Reached from `SKILL.md`'s Route table when the user asks to clean the cache or rebuild environments from scratch. Self-contained. + +## Gate — confirm first + +`pre-commit clean` wipes the whole cache at `~/.cache/pre-commit`, forcing every hook environment to be re-downloaded on the next run. Require explicit confirmation before executing it: + +> "This will wipe the entire pre-commit cache. All hook environments will be re-downloaded on next run. Proceed?" + +```bash +pre-commit clean +``` + +Prefer `pre-commit gc` when the goal is only to reclaim disk — it drops unused environments and leaves the ones in use intact, so it needs no confirmation. diff --git a/plugins/git/.apm/skills/pc-run/references/failure-patterns.md b/plugins/git/.apm/skills/pc-run/references/failure-patterns.md index efeb882..bfb3c65 100644 --- a/plugins/git/.apm/skills/pc-run/references/failure-patterns.md +++ b/plugins/git/.apm/skills/pc-run/references/failure-patterns.md @@ -18,6 +18,8 @@ git add -u git commit -m "same message" ``` +Do NOT reach for `pre-commit install -f` here. That flag overwrites existing hook files in `.git/hooks/`; it has nothing to do with re-staging. + ## Secret detected (gitleaks) > Not sourced from the pre-commit research corpus (`context7-pre-commit-com`/`pre-commit-com` cover pre-commit itself, not gitleaks) — general tool knowledge, verify against gitleaks' own docs if precision matters. diff --git a/plugins/git/.apm/skills/pc-run/references/install.md b/plugins/git/.apm/skills/pc-run/references/install.md new file mode 100644 index 0000000..e948f1b --- /dev/null +++ b/plugins/git/.apm/skills/pc-run/references/install.md @@ -0,0 +1,31 @@ +--- +source_keys: + - context7-pre-commit-com + - pre-commit-com +--- + +# Installing hooks into `.git/hooks/` + +Reached from `SKILL.md`'s Route table when the user asks to install or set up hooks. Self-contained. + +Only run this flow when the user explicitly asks for it. Installing rewrites their clone's `.git/hooks/`; it is never a side effect of another request. + +## Gate — existing hook files + +Check `ls .git/hooks/` first. With hook files already there, `pre-commit install` does not refuse — it silently enters migration mode and runs both. Only `-f` replaces them, and `pre-commit uninstall` cannot restore whatever `-f` overwrote. + +So when hook files are present, put the choice to the user in these terms, including the irreversibility, and wait for an answer before passing `-f`: + +> "Existing hook files found in `.git/hooks/`. Plain `pre-commit install` runs both; `-f` overwrites them permanently and `pre-commit uninstall` cannot restore them. Plain install, or overwrite?" + +## Install + +```bash +pre-commit install +``` + +Re-run with `-t` flags when `default_install_hook_types` changed, or when hooks in a non-default stage never fire — a hook whose stage was never installed cannot run: + +```bash +pre-commit install -t pre-commit -t pre-push -t commit-msg +``` diff --git a/plugins/git/.apm/skills/pc-run/references/sources.md b/plugins/git/.apm/skills/pc-run/references/sources.md index d4ad971..eb6a423 100644 --- a/plugins/git/.apm/skills/pc-run/references/sources.md +++ b/plugins/git/.apm/skills/pc-run/references/sources.md @@ -4,7 +4,7 @@ - **URL:** context7:/pre-commit/pre-commit.com - **Description:** Official pre-commit.com documentation — installation, configuration schema, CLI reference, hook authoring, advanced features, troubleshooting -- **Contributing files:** SKILL.md, references/failure-patterns.md +- **Contributing files:** SKILL.md, references/install.md, references/autoupdate.md, references/clean.md, references/failure-patterns.md - **Research doc:** plugins/git/docs/research/docs/pre-commit/{overview,cli-reference,troubleshooting}.md - **Status:** `extracted` @@ -12,7 +12,7 @@ - **URL:** https://pre-commit.com/ - **Description:** Pre-commit framework homepage — full docs covering install, config, CLI, hook authoring, stages, local hooks, meta hooks, hazmat helpers, CI integration -- **Contributing files:** SKILL.md, references/failure-patterns.md +- **Contributing files:** SKILL.md, references/install.md, references/autoupdate.md, references/clean.md, references/failure-patterns.md - **Research doc:** plugins/git/docs/research/docs/pre-commit/{overview,cli-reference,troubleshooting}.md - **Status:** `extracted` diff --git a/plugins/git/skills/pc-run/README.md b/plugins/git/skills/pc-run/README.md index 7113b56..be4b26c 100644 --- a/plugins/git/skills/pc-run/README.md +++ b/plugins/git/skills/pc-run/README.md @@ -24,6 +24,9 @@ Common invocations: | File | Purpose | |------|---------| | `SKILL.md` | Skill instructions for agents | -| `references/failure-patterns.md` | Hook failure causes and concrete fix suggestions | +| `references/install.md` | The install flow — loaded when the user asks to install or set up hooks | +| `references/autoupdate.md` | The autoupdate flow — loaded when the user asks to bump hook revs | +| `references/clean.md` | The clean flow — loaded when the user asks to wipe the cache or rebuild environments | +| `references/failure-patterns.md` | Hook failure causes and concrete fix suggestions — loaded when a hook fails or never fires | | `references/sources.md` | Provenance: research sources that informed this skill | | `references/README.md` | Directory index for references/ | diff --git a/plugins/git/skills/pc-run/SKILL.md b/plugins/git/skills/pc-run/SKILL.md index d603638..e1da3a3 100644 --- a/plugins/git/skills/pc-run/SKILL.md +++ b/plugins/git/skills/pc-run/SKILL.md @@ -1,13 +1,9 @@ --- name: pc-run description: > - Use when the user wants to run pre-commit hooks, install git hooks, update - hook versions, or maintain the pre-commit cache. Triggers on: "run - pre-commit", "run all hooks", "check everything passes", "install hooks", - "wire hooks into git", "update hook versions", "autoupdate", "bump revs", - "clean the cache", "rebuild environments", "gc", "why is my hook failing", - "hooks aren't running". Do not use for creating or editing - `.pre-commit-config.yaml` — use `pc-author` for that. + Use when the user wants to run pre-commit hooks, wire them into git, bump hook + revs, maintain the cache, or diagnose why a hook fails or never fires. Not + creating or editing the pre-commit config -> `pc-author`. compatibility: Requires pre-commit installed and available on PATH. @@ -22,102 +18,34 @@ allowed-tools: Bash Read ## Gotchas -- Hooks not running on `git commit` almost always means `pre-commit install` was never run in this clone. Git hooks are per-clone — they are not committed to the repo. -- When a hook modifies files (e.g. `trailing-whitespace`, `end-of-file-fixer`), the commit is blocked intentionally — the staged version is stale. The fix is `git add -u && git commit`. Do NOT call `pre-commit install -f` here; that is for overwriting existing hooks, not re-staging. -- `pre-commit autoupdate` modifies `.pre-commit-config.yaml` in-place. Re-read the file after calling it to show the user the updated `rev` values. -- The `SKIP` env var requires exact hook `id` values, comma-separated, no spaces: `SKIP=check-yaml,gitleaks git commit -m "msg"`. A space after the comma silently skips nothing. -- Never use `git commit --no-verify` (or `-n`) to bypass a failing hook. Hooks are the automated QA gate; bypassing them breaks the pipeline. Diagnose and fix the failure instead — see the hook-specific guidance below and in `references/failure-patterns.md`. -- A stages mismatch — hook stage not installed — means the hook was added to the config but `pre-commit install` was not re-run with the correct `-t` flags. Hooks in stages not listed under `default_install_hook_types` will never fire. +- The `SKIP` env var takes exact hook `id` values, comma-separated with no spaces: `SKIP=check-yaml,gitleaks git commit -m "msg"`. A space after a comma silently skips nothing instead of erroring. +- Never bypass a failing hook with `git commit --no-verify` (or `-n`). Hooks are the automated QA gate, so a bypassed commit pushes the failure downstream where it costs more — diagnose it instead. ## Route -Determine intent from the user's request, then execute the matching operation: +Determine intent from the user's request, then execute the matching operation. Where the matching row names a `references/` file, read that one file and no other — each flow file is self-contained. | User intent | Operation | |---|---| | "run", "check", "verify", "test hooks" | `pre-commit run --all-files` (default) | | "staged", "simulate commit" | `pre-commit run` (staged files only) | | "CI", "changed files only", "diff range" | `pre-commit run --from-ref --to-ref ` — prefer this over `--all-files` on large repos | -| "install", "set up hooks", "wire into git" | `pre-commit install` — see Install | -| "pre-create environments", "install-hooks", "warm cache" | `pre-commit install-hooks` — see Install | -| "remove hooks", "uninstall", "tear down pre-commit" | `pre-commit uninstall` | -| "autoupdate", "update versions", "bump revs" | `pre-commit autoupdate` | -| "gc", "garbage collect" | `pre-commit gc` | -| "clean", "wipe cache", "rebuild from scratch" | `pre-commit clean` — see Clean | +| "install", "set up hooks", "wire into git" | `pre-commit install` — read `references/install.md` | +| "pre-create environments", "warm cache" | `pre-commit install-hooks` — builds every hook environment without running a hook | +| "remove hooks", "uninstall", "tear down" | `pre-commit uninstall` — removes pre-commit from `.git/hooks/` | +| "autoupdate", "update versions", "bump revs" | `pre-commit autoupdate` — read `references/autoupdate.md` | +| "gc", "garbage collect" | `pre-commit gc` — drops unused cached environments only, safe at any time | +| "clean", "wipe cache", "rebuild from scratch" | `pre-commit clean` — read `references/clean.md` | +| "hooks aren't running", "hook never fires", "why did a hook fail" | Diagnose — read `references/failure-patterns.md` | If the intent is ambiguous, default to `pre-commit run --all-files`. ## Run -Default: `pre-commit run --all-files`. Never silently run staged-only. +Default to `pre-commit run --all-files`; never silently narrow to staged files. Run `pre-commit run` (staged only) or `pre-commit run ` (one named hook) when the user asks for it. -```bash -pre-commit run --all-files -``` +When hooks fail: -**When hooks fail**, read the output and: -1. Identify which hook failed and the specific cause. Be concrete: "gitleaks blocked `config.json` (high-entropy string on line 12)", not just "gitleaks failed". -2. Suggest a concrete next step. Common patterns are in `references/failure-patterns.md`. -3. Do NOT auto-fix code files. Do NOT modify `.pre-commit-config.yaml`. Those are the user's or `pc-author`'s responsibility. - -If the user asks to run only staged files: `pre-commit run` (no `--all-files`). -If the user names a specific hook: `pre-commit run `. - -## Install - -Only run when the user explicitly asks to install or set up hooks. - -Before running, check for existing hook files: - -```bash -ls .git/hooks/ -``` - -If any hook files exist (e.g. a hand-written `pre-commit`), `pre-commit install` does NOT refuse or error — it defaults to migration mode, which runs the existing hook and pre-commit's hooks both. Only `-f` replaces the existing hook file outright, and that replacement is not reversible via `pre-commit uninstall` — uninstall only removes pre-commit from `.git/hooks/`, it does not restore whatever hand-written hook `-f` overwrote. If files are present, tell the user: "Existing hook files found at `.git/hooks/`. Plain `pre-commit install` will run both; `pre-commit install -f` will overwrite them permanently instead. Proceed with plain install, or overwrite?" Wait for confirmation before using `-f`. - -```bash -pre-commit install -``` - -Re-run with `-t` flags when `default_install_hook_types` was changed or when hooks in non-default stages aren't firing: - -```bash -pre-commit install -t pre-commit -t pre-push -t commit-msg -``` - -To pre-create all hook environments without running hooks (useful for CI warm-up or first-time setup): - -```bash -pre-commit install-hooks -``` - -To remove pre-commit from `.git/hooks/` entirely: - -```bash -pre-commit uninstall -``` - -## Autoupdate - -```bash -pre-commit autoupdate -``` - -After it completes, read `.pre-commit-config.yaml` and report which `rev` values changed. If the user wants to pin to exact SHAs (for reproducibility): `pre-commit autoupdate --freeze`. - -## Clean and GC - -**`gc`** — removes only unused cached environments. Safe to run at any time: -```bash -pre-commit gc -``` - -**`clean`** — wipes the entire cache at `~/.cache/pre-commit`. All hook environments will be re-downloaded on next run. Require explicit confirmation before running: - -> "This will wipe the entire pre-commit cache. All hook environments will be re-downloaded on next run. Proceed?" - -Wait for the user to say yes before executing: - -```bash -pre-commit clean -``` +1. Name the hook and the specific cause. Be concrete — "gitleaks blocked `config.json` (high-entropy string on line 12)", not "gitleaks failed". +2. Suggest one concrete next step. If the cause is not obvious from the output, read `references/failure-patterns.md`. +3. Do not auto-fix code files, and do not edit `.pre-commit-config.yaml` — those belong to the user or to `pc-author`. diff --git a/plugins/git/skills/pc-run/references/README.md b/plugins/git/skills/pc-run/references/README.md index 4340626..51290f8 100644 --- a/plugins/git/skills/pc-run/references/README.md +++ b/plugins/git/skills/pc-run/references/README.md @@ -10,5 +10,8 @@ source_keys: | File | Purpose | |---|---| -| `failure-patterns.md` | Hook failure causes and concrete fix suggestions — loaded when hooks fail | +| `install.md` | The install flow — read when the user asks to install or set up hooks | +| `autoupdate.md` | The autoupdate flow — read when the user asks to bump hook revs | +| `clean.md` | The clean flow — read when the user asks to wipe the cache or rebuild environments | +| `failure-patterns.md` | Hook failure causes and concrete fix suggestions — read when a hook fails or never fires | | `sources.md` | Provenance: research sources that informed this skill | diff --git a/plugins/git/skills/pc-run/references/autoupdate.md b/plugins/git/skills/pc-run/references/autoupdate.md new file mode 100644 index 0000000..b222994 --- /dev/null +++ b/plugins/git/skills/pc-run/references/autoupdate.md @@ -0,0 +1,17 @@ +--- +source_keys: + - context7-pre-commit-com + - pre-commit-com +--- + +# Bumping hook revs with `autoupdate` + +Reached from `SKILL.md`'s Route table when the user asks to update hook versions or bump revs. Self-contained. + +```bash +pre-commit autoupdate +``` + +This rewrites `.pre-commit-config.yaml` in place, so re-read the file afterwards and report which `rev` values changed. It is the one operation in this skill that writes that file, and the exception is deliberate: the rewrite is pre-commit's own, resolved against the hook repos, not a hand edit — which is why `pc-author` hands rev bumps here rather than making them itself. + +Add `--freeze` when the user wants exact SHAs pinned for reproducibility. diff --git a/plugins/git/skills/pc-run/references/clean.md b/plugins/git/skills/pc-run/references/clean.md new file mode 100644 index 0000000..0ab452b --- /dev/null +++ b/plugins/git/skills/pc-run/references/clean.md @@ -0,0 +1,21 @@ +--- +source_keys: + - context7-pre-commit-com + - pre-commit-com +--- + +# Wiping the pre-commit cache + +Reached from `SKILL.md`'s Route table when the user asks to clean the cache or rebuild environments from scratch. Self-contained. + +## Gate — confirm first + +`pre-commit clean` wipes the whole cache at `~/.cache/pre-commit`, forcing every hook environment to be re-downloaded on the next run. Require explicit confirmation before executing it: + +> "This will wipe the entire pre-commit cache. All hook environments will be re-downloaded on next run. Proceed?" + +```bash +pre-commit clean +``` + +Prefer `pre-commit gc` when the goal is only to reclaim disk — it drops unused environments and leaves the ones in use intact, so it needs no confirmation. diff --git a/plugins/git/skills/pc-run/references/failure-patterns.md b/plugins/git/skills/pc-run/references/failure-patterns.md index efeb882..bfb3c65 100644 --- a/plugins/git/skills/pc-run/references/failure-patterns.md +++ b/plugins/git/skills/pc-run/references/failure-patterns.md @@ -18,6 +18,8 @@ git add -u git commit -m "same message" ``` +Do NOT reach for `pre-commit install -f` here. That flag overwrites existing hook files in `.git/hooks/`; it has nothing to do with re-staging. + ## Secret detected (gitleaks) > Not sourced from the pre-commit research corpus (`context7-pre-commit-com`/`pre-commit-com` cover pre-commit itself, not gitleaks) — general tool knowledge, verify against gitleaks' own docs if precision matters. diff --git a/plugins/git/skills/pc-run/references/install.md b/plugins/git/skills/pc-run/references/install.md new file mode 100644 index 0000000..e948f1b --- /dev/null +++ b/plugins/git/skills/pc-run/references/install.md @@ -0,0 +1,31 @@ +--- +source_keys: + - context7-pre-commit-com + - pre-commit-com +--- + +# Installing hooks into `.git/hooks/` + +Reached from `SKILL.md`'s Route table when the user asks to install or set up hooks. Self-contained. + +Only run this flow when the user explicitly asks for it. Installing rewrites their clone's `.git/hooks/`; it is never a side effect of another request. + +## Gate — existing hook files + +Check `ls .git/hooks/` first. With hook files already there, `pre-commit install` does not refuse — it silently enters migration mode and runs both. Only `-f` replaces them, and `pre-commit uninstall` cannot restore whatever `-f` overwrote. + +So when hook files are present, put the choice to the user in these terms, including the irreversibility, and wait for an answer before passing `-f`: + +> "Existing hook files found in `.git/hooks/`. Plain `pre-commit install` runs both; `-f` overwrites them permanently and `pre-commit uninstall` cannot restore them. Plain install, or overwrite?" + +## Install + +```bash +pre-commit install +``` + +Re-run with `-t` flags when `default_install_hook_types` changed, or when hooks in a non-default stage never fire — a hook whose stage was never installed cannot run: + +```bash +pre-commit install -t pre-commit -t pre-push -t commit-msg +``` diff --git a/plugins/git/skills/pc-run/references/sources.md b/plugins/git/skills/pc-run/references/sources.md index d4ad971..eb6a423 100644 --- a/plugins/git/skills/pc-run/references/sources.md +++ b/plugins/git/skills/pc-run/references/sources.md @@ -4,7 +4,7 @@ - **URL:** context7:/pre-commit/pre-commit.com - **Description:** Official pre-commit.com documentation — installation, configuration schema, CLI reference, hook authoring, advanced features, troubleshooting -- **Contributing files:** SKILL.md, references/failure-patterns.md +- **Contributing files:** SKILL.md, references/install.md, references/autoupdate.md, references/clean.md, references/failure-patterns.md - **Research doc:** plugins/git/docs/research/docs/pre-commit/{overview,cli-reference,troubleshooting}.md - **Status:** `extracted` @@ -12,7 +12,7 @@ - **URL:** https://pre-commit.com/ - **Description:** Pre-commit framework homepage — full docs covering install, config, CLI, hook authoring, stages, local hooks, meta hooks, hazmat helpers, CI integration -- **Contributing files:** SKILL.md, references/failure-patterns.md +- **Contributing files:** SKILL.md, references/install.md, references/autoupdate.md, references/clean.md, references/failure-patterns.md - **Research doc:** plugins/git/docs/research/docs/pre-commit/{overview,cli-reference,troubleshooting}.md - **Status:** `extracted`