---
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.

## 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 |

## Shell (`.sh`)

| Hook ID | Repo | Rev | Rationale |
|---------|------|-----|-----------|
| `shellcheck` | `https://github.com/jumanjihouse/pre-commit-hooks` | `3.0.0` | 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.21.2` | 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 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