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 Releases 页面进行检查。如果无法查询，则使用上方列出的版本。

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）。安装建议仅限于当前仓库；不要编辑个人软件包清单或点文件。

高级选项

特定阶段的钩子

缓慢的检查（测试、完整构建）应放在 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

单独设置 stages = ["pre-push"] 并不会安装 pre-push Git 垫片。在顶层配置中添加 default_install_hook_types = ["pre-commit", "pre-push"]（请根据 prek 文档核实键名），然后请用户重新运行已获授权的 prek install，以便 Git 安装 pre-push 垫片。prek run --hook-stage pre-push 会运行该阶段，但不能证明垫片本身已安装。

全局过滤器

将 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 中的 Rev 锁定会过时——建议定期更新
• prek install 需要对 .git/hooks/ 的写入权限——在共享钩子的 worktree 中会失败