pre-commit

What this skill does

# PreCommit

A comprehensive skill for managing [pre-commit](https://pre-commit.com/) hooks - the framework for multi-language pre-commit hook management that automates code quality, formatting, linting, and security scanning.

## Quick Reference

| Command | Description |
|---------|-------------|
| `pre-commit install` | Install git hooks |
| `pre-commit run --all-files` | Run all hooks on all files |
| `pre-commit autoupdate` | Update hooks to latest versions |
| `pre-commit run <hook-id>` | Run specific hook |

## Workflow Routing

| Workflow | Trigger | File |
|----------|---------|------|
| **Setup** | "setup pre-commit", "initialize hooks", "create config" | `Workflows/Setup.md` |
| **AddHooks** | "add hook", "add linting", "add formatter", "add security" | `Workflows/AddHooks.md` |
| **Troubleshoot** | "fix pre-commit", "hook failing", "debug hooks" | `Workflows/Troubleshoot.md` |
| **CIIntegration** | "CI pipeline", "GitHub Actions", "GitLab CI" | `Workflows/CIIntegration.md` |
| **CustomHook** | "create custom hook", "local hook", "write hook" | `Workflows/CustomHook.md` |

## Documentation

| Document | Purpose |
|----------|---------|
| `QuickStartGuide.md` | Installation and first-time setup |
| `HooksReference.md` | Comprehensive hook catalog by language/purpose |
| `ConfigurationGuide.md` | Advanced configuration options |
| `SecurityHooks.md` | Secret detection and security scanning |

## Tools

| Tool | Purpose |
|------|---------|
| `Tools/PreCommitManager.ts` | CLI for managing pre-commit configurations |
| `Tools/HookGenerator.ts` | Generate .pre-commit-config.yaml templates |
| `Tools/HookValidator.ts` | Validate hook configurations |

## Examples

**Example 1: Setup pre-commit for a new project**
```
User: "Setup pre-commit for my Python project"
→ Invokes Setup workflow
→ Creates .pre-commit-config.yaml with Python hooks (black, isort, flake8)
→ Runs pre-commit install
```

**Example 2: Add Terraform hooks**
```
User: "Add Terraform validation hooks"
→ Invokes AddHooks workflow
→ Adds terraform_fmt, terraform_validate, terraform_docs hooks
→ Configures tflint and checkov integration
```

**Example 3: Add security scanning**
```
User: "Add secret detection to pre-commit"
→ Invokes AddHooks workflow
→ Adds gitleaks, detect-secrets, trufflehog hooks
→ Configures appropriate exclusion patterns
```

**Example 4: Debug failing hook**
```
User: "My eslint pre-commit hook is failing"
→ Invokes Troubleshoot workflow
→ Checks hook configuration and dependencies
→ Provides fix recommendations
```

## Supported Hook Categories

- **Python**: black, isort, flake8, mypy, bandit, pyupgrade
- **JavaScript/TypeScript**: prettier, eslint, biome
- **Infrastructure**: terraform, terragrunt, helm, kustomize
- **Kubernetes**: kubeconform, kubeval, checkov
- **Security**: gitleaks, detect-secrets, trufflehog, trivy
- **General**: yamllint, jsonlint, shellcheck, markdownlint

---

## Gotchas

- **Hook output disappears when run via `git commit -m` in an editor terminal** — stdout/stderr get swallowed by the editor wrapping. Run `pre-commit run --all-files` directly to see the actual failure message.
- **`pre-commit autoupdate` bumps to latest tag but doesn't update pinned config in hook repos** — a hook that pins `flake8==6.0.0` internally keeps that version. Look at each hook's `additional_dependencies` after autoupdate.
- **Hooks only run on staged files by default**, so editing a file after `git add` and then committing runs the hook against the OLD content. Use `--all-files` in CI to catch this.
- **`exclude:` regex is anchored differently than `files:`** — `exclude: tests/` does NOT exclude `tests/foo.py` in some hook versions; use `exclude: ^tests/` to be safe. Anchor everything.
- **`language: system` hooks bypass the pre-commit venv** and rely on the user's PATH — works on your machine, fails in CI with `command not found`. Prefer `language: python` with `additional_dependencies`.
- **`pre-commit install` doesn't install for `commit-msg` or `pre-push`** by default — separate `--hook-type` calls needed. Many teams add commit-msg hooks then wonder why they don't fire.
- **Skipping a hook via `SKIP=hookid git commit` is per-shell-invocation**, not per-commit — CI runs with a fresh env where SKIP is unset and the hook fires anyway.