refactor(pc-run): retrofit to the ADR-0020 context contract
Description 477 -> 211 chars, body 736 -> 367 words. Install, autoupdate, and clean become flow files behind the Route table. The audit found no route for 'hooks aren't running': the only pointer to failure-patterns.md sat inside the failure path, but when hooks never fire the manual run succeeds, so the request fell to the ambiguity default and was masked. Restores the disclosure that install -f is not reversible by uninstall.
This commit is contained in:
@@ -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/ |
|
||||
|
||||
@@ -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 <base> --to-ref <head>` — 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 <hook-id>` (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 <hook-id>`.
|
||||
|
||||
## 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/<names>`. 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`.
|
||||
|
||||
@@ -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 |
|
||||
|
||||
17
plugins/git/.apm/skills/pc-run/references/autoupdate.md
Normal file
17
plugins/git/.apm/skills/pc-run/references/autoupdate.md
Normal file
@@ -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.
|
||||
21
plugins/git/.apm/skills/pc-run/references/clean.md
Normal file
21
plugins/git/.apm/skills/pc-run/references/clean.md
Normal file
@@ -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.
|
||||
@@ -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.
|
||||
|
||||
31
plugins/git/.apm/skills/pc-run/references/install.md
Normal file
31
plugins/git/.apm/skills/pc-run/references/install.md
Normal file
@@ -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
|
||||
```
|
||||
@@ -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`
|
||||
|
||||
|
||||
@@ -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/ |
|
||||
|
||||
@@ -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 <base> --to-ref <head>` — 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 <hook-id>` (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 <hook-id>`.
|
||||
|
||||
## 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/<names>`. 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`.
|
||||
|
||||
@@ -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 |
|
||||
|
||||
17
plugins/git/skills/pc-run/references/autoupdate.md
Normal file
17
plugins/git/skills/pc-run/references/autoupdate.md
Normal file
@@ -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.
|
||||
21
plugins/git/skills/pc-run/references/clean.md
Normal file
21
plugins/git/skills/pc-run/references/clean.md
Normal file
@@ -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.
|
||||
@@ -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.
|
||||
|
||||
31
plugins/git/skills/pc-run/references/install.md
Normal file
31
plugins/git/skills/pc-run/references/install.md
Normal file
@@ -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
|
||||
```
|
||||
@@ -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`
|
||||
|
||||
|
||||
Reference in New Issue
Block a user