holocron/plugins/git/skills/pc-author/references/hooks-by-language.md

---
source_keys:
  - context7-pre-commit-com
  - pre-commit-com
  - context7-pre-commit-hooks
  - pre-commit-hooks-github
---

# Hook Recommendations by Language / Context

Use this table when creating a config from scratch or recommending hooks to add.
Always check the existing config for duplicates before proposing.

Fixer hooks (`trailing-whitespace`, `end-of-file-fixer`, `pretty-format-json` and the like) rewrite
files but do NOT re-stage them, so the commit is still blocked and the user has to stage and commit
again. Say so when proposing one — otherwise the first blocked commit reads as the hook being
broken.

## Universal (recommend for every repo)

| Hook ID | Repo | Rev | Rationale |
|---------|------|-----|-----------|
| `end-of-file-fixer` | `https://github.com/pre-commit/pre-commit-hooks` | `v6.0.0` | Ensures files end with a newline — prevents spurious diffs |
| `trailing-whitespace` | `https://github.com/pre-commit/pre-commit-hooks` | `v6.0.0` | Strips trailing whitespace — prevents invisible diff noise |
| `check-merge-conflict` | `https://github.com/pre-commit/pre-commit-hooks` | `v6.0.0` | Catches unresolved merge markers before commit |
| `detect-private-key` | `https://github.com/pre-commit/pre-commit-hooks` | `v6.0.0` | Blocks PEM private key material |
| `check-added-large-files` | `https://github.com/pre-commit/pre-commit-hooks` | `v6.0.0` | Blocks accidentally committing large binary files |
| `check-case-conflict` | `https://github.com/pre-commit/pre-commit-hooks` | `v6.0.0` | Catches filenames that would collide on case-insensitive filesystems |
| `mixed-line-ending` | `https://github.com/pre-commit/pre-commit-hooks` | `v6.0.0` | Normalizes line endings |
| `no-commit-to-branch` | `https://github.com/pre-commit/pre-commit-hooks` | `v6.0.0` | Blocks direct commits to protected branches — defaults to blocking `main`+`master` with no args; add `args: [--branch, <name>]` only to protect additional branch names |

## Shell (`.sh`)

| Hook ID | Repo | Rev | Rationale |
|---------|------|-----|-----------|
| `shellcheck` | `https://github.com/jumanjihouse/pre-commit-hooks` | `3.0.0` | **Unverified — not in research corpus, verify upstream before use.** Static analysis for shell scripts; catches common errors |

Recommended args: `args: [--severity=warning]`

## Python (`.py`)

| Hook ID | Repo | Rev | Rationale |
|---------|------|-----|-----------|
| `check-ast` | `https://github.com/pre-commit/pre-commit-hooks` | `v6.0.0` | Validates Python files parse as valid AST |
| `check-builtin-literals` | `https://github.com/pre-commit/pre-commit-hooks` | `v6.0.0` | Enforces literal syntax for `dict()`, `list()` |

For formatting: check if `black`, `ruff`, or `isort` is already configured in `pyproject.toml` before recommending them.

## JSON (`.json`)

| Hook ID | Repo | Rev | Rationale |
|---------|------|-----|-----------|
| `check-json` | `https://github.com/pre-commit/pre-commit-hooks` | `v6.0.0` | Validates JSON parses correctly |
| `pretty-format-json` | `https://github.com/pre-commit/pre-commit-hooks` | `v6.0.0` | Auto-formats JSON (fixer — warns user to re-stage after commit) |

## YAML (`.yaml`, `.yml`)

| Hook ID | Repo | Rev | Rationale |
|---------|------|-----|-----------|
| `check-yaml` | `https://github.com/pre-commit/pre-commit-hooks` | `v6.0.0` | Validates YAML parses correctly |

For Kubernetes/Helm YAML with custom tags, add `args: ['--unsafe']` and `exclude: ^helm/templates/`.

## TOML (`.toml`)

| Hook ID | Repo | Rev | Rationale |
|---------|------|-----|-----------|
| `check-toml` | `https://github.com/pre-commit/pre-commit-hooks` | `v6.0.0` | Validates TOML parses correctly |

## Secrets / security

| Hook ID | Repo | Rev | Rationale |
|---------|------|-----|-----------|
| `gitleaks` | `https://github.com/gitleaks/gitleaks` | `v8.30.1` | **Unverified — not in research corpus, verify upstream before use.** Scans for secrets and high-entropy strings |

## Commit message

| Hook ID | Repo | Rev | Stage | Rationale |
|---------|------|-----|-------|-----------|
| `conventional-pre-commit` | `https://github.com/compilerla/conventional-pre-commit` | `v2.4.0` | `commit-msg` | Enforces Conventional Commits format |

When adding commit-msg hooks, also add `default_install_hook_types: [pre-commit, commit-msg]` to the top-level config if not already present.

## Meta-validation (add last, after all other repos)

```yaml
- repo: meta
  hooks:
    - id: check-hooks-apply       # catches hooks that match no files
    - id: check-useless-excludes  # catches exclude patterns that match no files
```

## Local hooks (repo: local)

Use for repo-specific scripts that don't belong in an external hook repo.

```yaml
- repo: local
  hooks:
    - id: run-tests
      name: Run test suite
      entry: bash tests/run-tests.sh
      language: unsupported_script
      pass_filenames: false
      always_run: true
      stages: [pre-push]
```

`language: system` and `language: script` are deprecated names for the first two below.
New local hooks use `unsupported` and `unsupported_script`.

Language choices for local hooks:
- `unsupported` — system PATH tool (pre-commit does not manage env)
- `unsupported_script` — script at a repo-relative path
- `fail` — always-fail guard; `entry` text becomes the error message
- `python` — isolated venv; use `additional_dependencies` for pip packages
- `node` — isolated node env; `additional_dependencies` are npm packages
- `ruby` — isolated gem env; `additional_dependencies` are gems
- `golang` — builds from source; `additional_dependencies` are Go module paths
- `rust` — Cargo build
- `docker` — Docker image built from `entry`; use when no other language fits
- `docker_image` — pulls a pre-built Docker image by `entry`
- `conda` — Conda environment; conda-native hooks
- `coursier` — Coursier (Scala/JVM) environment; JVM hooks

## Rev pin freshness

The revs above were last verified current at time of writing (matched against the plugin's own research corpus in `docs/research/docs/pre-commit/`; rows marked "Unverified" have no such backing and must be checked against upstream before use). Since the "Rev staleness" check in `references/modify-config.md` treats this table as ground truth, a pin that goes stale here produces false-positive staleness warnings for users who already have a newer, correct rev. Re-verify these pins periodically (e.g. against each repo's latest release tag). When in doubt, treat `pre-commit autoupdate`'s own output as the authoritative staleness signal, not a mismatch against this table.