Defame1297
0239b00944
## Why The git plugin only covered a partial slice of common git workflows. This adds the remaining skill set (branches, commits, history, remotes, submodules, workflow, worktrees) plus a git-orchestrate agent so the plugin can handle end-to-end git automation instead of a handful of commands. ## Implementation Notes Each new skill was validated against its research docs and org conventions after initial authoring, which surfaced hallucinated version pins, factual errors, and completeness gaps that were corrected in the same pass rather than left for follow-up. ## Impact Bumps the git plugin to 1.3.0. Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
131 lines
4.2 KiB
Markdown
131 lines
4.2 KiB
Markdown
---
|
|
source_keys:
|
|
- context7-pre-commit-com
|
|
- pre-commit-com
|
|
---
|
|
|
|
# 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.
|
|
```bash
|
|
git add -u
|
|
git commit -m "same message"
|
|
```
|
|
|
|
## 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.
|
|
|
|
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:allow` inline 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 `$?`): use `if command; then` directly.
|
|
|
|
## `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:
|
|
```bash
|
|
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:
|
|
```bash
|
|
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:
|
|
```bash
|
|
pre-commit clean # wipe all environments
|
|
pre-commit install-hooks # rebuild everything
|
|
```
|
|
|
|
Or less destructively:
|
|
```bash
|
|
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:
|
|
```bash
|
|
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 `id` under a hook block
|
|
- Missing `rev` under a non-local repo block
|
|
- `repo: local` hook missing `language` or `entry`
|
|
- Indentation error (valid YAML but invalid pre-commit schema)
|