Defame1297
93d3263f8c
SKILL.md tells a dispatching agent to read the matching reference file "and no other". The retrofit moved the `pre-commit clean` confirmation gate out of the always-loaded body into references/clean.md, but references/failure-patterns.md — loaded by the diagnosis route, not the clean route — prescribes `pre-commit clean` with no gate at all. So "why is this hook failing" could wipe the machine-wide cache at ~/.cache/pre-commit for every repo without asking. The gate returns to the body, where every branch loads it, and is restated at the point of use in failure-patterns.md. It is its own section rather than a Gotchas bullet because folding it in pushed the Gotchas ratio to 41%, whose only suggested remedy is moving it back to references/ — the move that caused this. The fixer-hook rule had the same shape: reachable only behind "if the cause is not obvious from the output", which is false precisely when pre-commit prints `- files were modified by this hook`. The fix (`git add -u && git commit`) and the prohibition on `pre-commit install -f` are now unconditional, and the two weakened pointers that stranded them are restored. Found by an independent review of this branch. Refs #99
4.7 KiB
source_keys
| source_keys | ||
|---|---|---|
|
Hook Failure Patterns
Common hook failure causes and concrete next-step suggestions.
Hook modified files — commit blocked
Cause: A fixer hook (e.g. trailing-whitespace, end-of-file-fixer, pretty-format-json) modified staged files. The commit is blocked because the staged version is now stale.
Fix: Re-stage and recommit.
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-comcover pre-commit itself, not gitleaks) — general tool knowledge, verify against gitleaks' own docs if precision matters.
Cause: gitleaks found a high-entropy string or known secret pattern in a staged file.
Suggestions:
- If it's a false positive: add a
# gitleaks:allowinline comment, or add the path to.gitleaksignore. - If it's a real secret: remove it from the file, rotate the credential, then commit.
Shellcheck warning
Not sourced from the pre-commit research corpus — general tool knowledge, verify against shellcheck's own docs if precision matters.
Cause: shellcheck found a shell script issue. The output includes the file path, line number, and SC-code.
Fix: Look up the SC-code on shellcheck.net or pass --explain SCxxxx to shellcheck for a detailed explanation. The most common fixes:
- SC2086 (unquoted variable): wrap in double quotes.
- SC2046 (unquoted command substitution): wrap in double quotes.
- SC2181 (check exit code of
$?): useif command; thendirectly.
check-hooks-apply fails
Cause: A hook's files/types filter matches zero files in the repo — the hook is dead weight.
Fix: Broaden the filter, or remove the hook if it no longer applies to this repo.
check-useless-excludes fails
Cause: An exclude pattern matches no files.
Fix: Remove or fix the pattern.
SSH cloning fails in CI
Cause: The CI environment lacks SSH credentials to clone hook repos over SSH.
Fix: Export SSH_AUTH_SOCK in the CI environment, or switch hook repo URLs to HTTPS.
HTTP proxy needed
Cause: The CI/sandbox network requires a proxy to reach hook repos.
Fix:
export http_proxy=http://proxy.example.com:3128
export https_proxy=http://proxy.example.com:3128
export no_proxy=localhost,127.0.0.1
rev is a branch name — autoupdate broke it
Cause: Branch refs are mutable and drift over time; pre-commit resolves them once at install time, so pinning to a branch name (instead of a tag or commit SHA) leads to silent version drift.
Fix:
pre-commit autoupdate # finds the latest tag and rewrites rev in place
pretty-format-json fails but doesn't fix
Cause: pretty-format-json requires args: [--autofix] to modify files. Without it, the hook only fails.
Fix: The user (or pc-author) must add args: [--autofix] to the hook override in .pre-commit-config.yaml.
Environment stale or broken
Cause: A hook's cached environment is corrupted or out of date.
Fix: pre-commit clean is gated. It wipes the machine-wide cache at ~/.cache/pre-commit, shared by every repo on the box, so get explicit confirmation before running it — "This will wipe the entire pre-commit cache. All hook environments will be re-downloaded on next run. Proceed?"
pre-commit clean # gated — confirm with the user first
pre-commit install-hooks # rebuild everything
Or less destructively, needing no confirmation:
pre-commit gc # remove only unused environments
Hooks don't run on git commit
Cause: pre-commit install was never run in this clone.
Fix: pre-commit install. Git hooks are per-clone — they are not committed to the repo.
Hook runs but matches wrong files (or no files)
Cause: The files: pattern uses re.search() not full-string match. A pattern that looks correct may match unexpectedly.
Diagnosis: identify-cli <filename> shows the type tags for a file. Verify types: filters against these.
stages mismatch — hook never fires
Cause: Hook is defined for a stage (e.g. pre-push) but pre-commit install was not run with -t pre-push.
Fix:
pre-commit install -t pre-commit -t pre-push -t commit-msg
Or add default_install_hook_types to .pre-commit-config.yaml and re-run pre-commit install.
validate-config schema error
Common causes:
- Missing
idunder a hook block - Missing
revunder a non-local repo block repo: localhook missinglanguageorentry- Indentation error (valid YAML but invalid pre-commit schema)