prek

prek

为 prek 配置并完成接入——一款由 Rust 驱动的快速 pre-commit 钩子管理器。

适用场景

• 项目没有 prek.toml，且适合使用 pre-commit 钩子
• 用户想在现有 prek.toml 中添加、审查或扩展钩子
• 用户正从 .pre-commit-config.yaml 迁移到 prek 原生 TOML 格式

流程

1. 检测项目类型

扫描仓库根目录中的语言标记：

标记文件	语言/框架
Cargo.toml	Rust
pyproject.toml、setup.py、requirements.txt	Python
package.json	TypeScript/JavaScript
go.mod	Go
Gemfile	Ruby
*.sh、zsh/、bin/	Shell
Dockerfile	Docker

存在多个标记表示这是多语言项目。为所有检测到的语言推荐钩子。

2. 检查现有配置

• 如果存在 prek.toml，读取并确认已配置的内容
• 如果存在 .pre-commit-config.yaml，询问是否迁移（prek 可原生读取 YAML，但 TOML 是原生格式，支持 glob 模式等更多功能）

3. 推荐钩子

按类别展示钩子。添加之前说明每个钩子的作用。参考如下：

内置钩子（repo = "builtin"）

快速、离线、无需设置。始终将这些作为基础推荐：

钩子 ID	功能
trailing-whitespace	删除行尾空格。参数：--markdown-linebreak-ext=md
end-of-file-fixer	确保文件以换行符结尾
check-yaml	验证 YAML 语法。参数：--allow-multiple-documents
check-toml	验证 TOML 语法
check-json	验证 JSON 语法（拒绝重复键）
check-json5	验证 JSON5 语法
check-xml	验证 XML 语法
check-merge-conflict	检测未解决的合并冲突标记
detect-private-key	捕获意外提交的私钥
check-added-large-files	阻止大文件。参数：--maxkb=1024
check-case-conflict	检测仅大小写不同的文件名
check-symlinks	验证符号链接是否指向现有目标
check-executables-have-shebangs	确保可执行脚本包含 shebang
mixed-line-ending	检测混合换行符（LF 与 CRLF）
fix-byte-order-marker	移除 UTF-8 BOM
no-commit-to-branch	阻止直接提交到受保护的分支

特定语言的钩子（社区仓库）

Rust：

# Local hooks (no external repo needed)
[[repos]]
repo = "local"

[[repos.hooks]]
id = "cargo-fmt"
name = "cargo fmt"
language = "system"
entry = "cargo fmt --"
files = "\\.rs$"
pass_filenames = true

[[repos.hooks]]
id = "cargo-clippy"
name = "cargo clippy"
language = "system"
entry = "cargo clippy --all-targets --all-features -- -D warnings"
files = "\\.rs$"
pass_filenames = false
always_run = true

Python：

# Ruff (linter + formatter)
[[repos]]
repo = "https://github.com/astral-sh/ruff-pre-commit"
rev = "v0.11.6"
hooks = [
  { id = "ruff", args = ["--fix"] },
  { id = "ruff-format" },
]

TypeScript/JavaScript：

[[repos]]
repo = "local"

[[repos.hooks]]
id = "eslint"
name = "eslint"
language = "system"
entry = "npx eslint --fix"
files = "\\.(ts|tsx|js|jsx)$"
pass_filenames = true

[[repos.hooks]]
id = "prettier"
name = "prettier"
language = "system"
entry = "npx prettier --write"
files = "\\.(ts|tsx|js|jsx|json|css|md)$"
pass_filenames = true

Go：

[[repos]]
repo = "local"

[[repos.hooks]]
id = "go-fmt"
name = "go fmt"
language = "system"
entry = "gofmt -w"
files = "\\.go$"
pass_filenames = true

[[repos.hooks]]
id = "go-vet"
name = "go vet"
language = "system"
entry = "go vet ./..."
pass_filenames = false
always_run = true

Shell：

[[repos]]
repo = "https://github.com/shellcheck-py/shellcheck-py"
rev = "a23f6b85d0fdd5bb9d564e2579e678033debbdff"
hooks = [
  { id = "shellcheck" },
]

4. 获取最新版本

写入配置前，检查社区钩子仓库当前推荐的版本（ruff-pre-commit、shellcheck-py 等）——可通过 Context7 MCP（如果你的运行环境提供）、运行环境的文档查询工具，或仓库的 GitHub 发布页面进行查询。如果无法查询，则使用上方列出的版本。

5. 生成或扩充 prek.toml

新项目：生成完整的 prek.toml，其中包含：

1. 内置钩子（始终包含：trailing-whitespace、end-of-file-fixer、check-merge-conflict、detect-private-key、check-added-large-files）
2. 根据检测结果添加特定语言的钩子
3. 用注释说明各个部分

现有项目：展示将要添加内容的差异。不要重复添加已有钩子。

6. 安装并验证

写入配置后：

prek install
prek run --all-files

如果未安装 prek，请告知用户安装它（cargo install prek 或 brew install prek）；如果存在 packages.yaml，也将其添加到该文件中。

高级选项

特定阶段的钩子

耗时的检查（测试、完整构建）应放在 pre-push 阶段，而不是 pre-commit 阶段：

[[repos.hooks]]
id = "pytest"
name = "Run tests"
language = "system"
entry = "pytest -x"
pass_filenames = false
always_run = true
stages = ["pre-push"]
priority = 100

全局过滤器

从所有钩子中排除 vendored/generated 代码：

exclude = "^(vendor/|generated/|node_modules/)"

Glob 模式（仅 prek 支持）

Prek 支持使用 glob 模式替代正则表达式（与上游 pre-commit 不兼容）：

files = { glob = "src/**/*.py" }
exclude = { glob = ["vendor/**", "dist/**"] }

从 pre-commit 迁移

如果存在 .pre-commit-config.yaml：

1. prek 原生读取 YAML —— 现有配置可直接使用
2. 建议转换为 prek.toml，以使用仅 prek 提供的功能（glob 模式、repo: builtin）
3. 对于受支持的钩子，将 repo: https://github.com/pre-commit/pre-commit-hooks 替换为 repo: builtin

不会执行的操作

• 配置 CI 流水线、GitHub Actions 或其他 CI 钩子系统
• 管理 husky、lint-staged 或 pre-commit（Python）配置
• 未经用户确认移除现有钩子
• 直接修改 .pre-commit-config.yaml —— 只生成 prek.toml

注意事项

• Context7 可能不可用 —— 钩子建议改用训练数据
• 如果自动修复钩子重新格式化所有内容，prek run --all-files 可能会在首次运行时失败
• prek.toml 中的修订版本固定可能会过时 —— 建议定期更新
• prek install 需要对 .git/hooks/ 的写入权限 —— 在共享钩子的 worktree 中会失败