Back to Details

prek

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

prek

prek

Onboard and configure prek — a fast, Rust-powered pre-commit hook manager.
接入并配置 prek——一款快速、基于 Rust 的 pre-commit hook 管理器。

When to use

使用场景

  • Project has no 
    prek.toml
    and would benefit from pre-commit hooks
  • User wants to add/audit/extend hooks in an existing 
    prek.toml
  • User is migrating from 
    .pre-commit-config.yaml
    to prek's native TOML format
  • 项目没有 
    prek.toml
    ，且可从 pre-commit hooks 中获益
  • 用户希望在现有 
    prek.toml
    中添加、审查或扩展 hooks
  • 用户正从 
    .pre-commit-config.yaml
    迁移到 prek 原生 TOML 格式

Protocol

协议

1. Detect project type

1. 检测项目类型

Scan the repo root for language markers:
Marker fileLanguage/Framework
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
Multiple markers = polyglot project. Suggest hooks for all detected languages.
扫描仓库根目录中的语言标记：
标记文件语言/框架
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
存在多个标记表示这是多语言项目。为所有检测到的语言推荐 hooks。

2. Check existing config

2. 检查现有配置

  • If 
    prek.toml
    exists, read it and identify what's already configured
  • If 
    .pre-commit-config.yaml
    exists, offer to migrate (prek reads YAML natively, but TOML is the native format with more features like glob patterns)
  • 如果存在 
    prek.toml
    ，读取它并确定已经配置的内容
  • 如果存在 
    .pre-commit-config.yaml
    ，提供迁移选项（prek 原生支持读取 YAML，但 TOML 是其原生格式，并提供 glob patterns 等更多功能）

3. Suggest hooks

3. 推荐 hooks

Present hooks in categories. Show what each hook does before adding. Use this reference:
按类别展示 hooks。添加前说明每个 hook 的作用。使用以下参考：

Built-in hooks (repo = "builtin")

内置 hooks（
repo = "builtin"
）

Fast, offline, zero-setup. Always suggest these as the foundation:
Hook IDWhat it does
trailing-whitespace
Trims trailing whitespace. Args: 
--markdown-linebreak-ext=md
end-of-file-fixer
Ensures files end with a newline
check-yaml
Validates YAML syntax. Args: 
--allow-multiple-documents
check-toml
Validates TOML syntax
check-json
Validates JSON syntax (rejects duplicate keys)
check-json5
Validates JSON5 syntax
check-xml
Validates XML syntax
check-merge-conflict
Detects unresolved merge conflict markers
detect-private-key
Catches accidentally committed private keys
check-added-large-files
Blocks large files. Args: 
--maxkb=1024
check-case-conflict
Detects filenames that differ only by case
check-symlinks
Validates symlinks point to existing targets
check-executables-have-shebangs
Ensures executable scripts have shebangs
mixed-line-ending
Detects mixed line endings (LF vs CRLF)
fix-byte-order-marker
Removes UTF-8 BOM
no-commit-to-branch
Blocks direct commits to protected branches
快速、离线、零配置。始终将这些作为基础推荐：
Hook 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
阻止直接向受保护分支提交

Language-specific hooks (community repos)

语言特定 hooks（社区仓库）

Rust:
toml
undefined
Rust：
toml
undefined

Local hooks (no external repo needed)

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:**

```toml
[[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：**

```toml

Ruff (linter + formatter)

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:**

```toml
[[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:
toml
[[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:
toml
[[repos]]
repo = "https://github.com/shellcheck-py/shellcheck-py"
rev = "a23f6b85d0fdd5bb9d564e2579e678033debbdff"
hooks = [
  { id = "shellcheck" },
]
[[repos]] repo = "https://github.com/astral-sh/ruff-pre-commit" rev = "v0.11.6" hooks = [ { id = "ruff", args = ["--fix"] }, { id = "ruff-format" }, ]

**TypeScript/JavaScript：**

```toml
[[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：
toml
[[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：
toml
[[repos]]
repo = "https://github.com/shellcheck-py/shellcheck-py"
rev = "a23f6b85d0fdd5bb9d564e2579e678033debbdff"
hooks = [
  { id = "shellcheck" },
]

4. Fetch latest versions

4. 获取最新版本

Before writing config, check the community hook repos for their current recommended versions (ruff-pre-commit, shellcheck-py, etc.) — via the Context7 MCP if your harness has it, your harness's doc-lookup tool, or the repos' GitHub releases pages. Fall back to the versions listed above if no lookup is available.
写入配置前，检查社区 hook 仓库当前推荐的版本（ruff-pre-commit、shellcheck-py 等）——如果 harness 提供 Context7 MCP，则使用它；也可使用 harness 的文档查询工具或仓库的 GitHub Releases 页面。如果无法查询，则回退到上述版本。

5. Generate or augment prek.toml

5. 生成或扩展 prek.toml

New project: Generate a complete 
prek.toml
with:
  1. Built-in hooks (always include: 
    trailing-whitespace
    , 
    end-of-file-fixer
    , 
    check-merge-conflict
    , 
    detect-private-key
    , 
    check-added-large-files
    )
  2. Language-specific hooks based on detection
  3. Comments explaining each section
Existing project: Show a diff of what would be added. Don't duplicate hooks already present.
新项目：生成完整的 
prek.toml
，其中包括：
  1. 内置 hooks（始终包含：
    trailing-whitespace
    、
    end-of-file-fixer
    、
    check-merge-conflict
    、
    detect-private-key
    、
    check-added-large-files
    ）
  2. 根据检测结果添加语言特定 hooks
  3. 用于说明各部分的注释
现有项目：显示将要添加内容的 diff。不要重复已经存在的 hooks。

6. Install and verify

6. 安装并验证

Ask the user before running these commands. For an audit or a proposed config change, stop at the proposed diff and do not run either command unless the user authorizes installation or a mutating run:
bash
prek install
prek run --all-files
If 
prek
isn't installed, tell the user to install it (
cargo install prek
or 
brew install prek
). Keep installation advice scoped to this repository; do not edit personal package manifests or dotfiles.
运行以下命令前先询问用户。对于审查或配置变更提案，停在拟议 diff 处；除非用户授权安装或执行可能修改文件的运行，否则不要运行上述任一命令：
bash
prek install
prek run --all-files
如果尚未安装 
prek
，告知用户可以通过 
cargo install prek
或 
brew install prek
安装。安装建议仅限于当前仓库；不要修改个人 package manifests 或 dotfiles。

Advanced options

高级选项

Stage-specific hooks

阶段特定 hooks

Slow checks (tests, full builds) belong on 
pre-push
, not 
pre-commit
:
toml
[[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"]
alone does not install a pre-push Git shim. Add 
default_install_hook_types = ["pre-commit", "pre-push"]
to the top-level config (verify the key name against the prek docs), then ask the user to rerun the authorized 
prek install
so Git installs the pre-push shim. 
prek run --hook-stage pre-push
runs the stage but does not prove the shim itself is installed.
较慢的检查（测试、完整构建）应放在 
pre-push
阶段，而不是 
pre-commit
：
toml
[[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 shim。在顶层配置中添加 
default_install_hook_types = ["pre-commit", "pre-push"]
（请对照 prek 文档确认键名），然后请用户重新运行已授权的 
prek install
，以便 Git 安装 pre-push shim。
prek run --hook-stage pre-push
会运行该阶段，但不能证明 shim 已安装。

Global filters

全局过滤器

Exclude vendored/generated code from all hooks:
toml
exclude = "^(vendor/|generated/|node_modules/)"
从所有 hooks 中排除 vendored/generated 代码：
toml
exclude = "^(vendor/|generated/|node_modules/)"

Glob patterns (prek-only)

Glob patterns（prek 专属）

Prek supports glob patterns as an alternative to regex (not compatible with upstream pre-commit):
toml
files = { glob = "src/**/*.py" }
exclude = { glob = ["vendor/**", "dist/**"] }
Prek 支持使用 glob patterns 作为 regex 的替代方案（与上游 pre-commit 不兼容）：
toml
files = { glob = "src/**/*.py" }
exclude = { glob = ["vendor/**", "dist/**"] }

Migration from pre-commit

从 pre-commit 迁移

If 
.pre-commit-config.yaml
exists:
  1. prek reads YAML natively — the existing config works as-is
  2. Offer to convert to 
    prek.toml
    for access to prek-only features (glob patterns, 
    repo: builtin
    )
  3. Replace 
    repo: https://github.com/pre-commit/pre-commit-hooks
    with 
    repo: builtin
    where hooks are supported
如果存在 
.pre-commit-config.yaml
：
  1. prek 原生支持读取 YAML——现有配置可直接使用
  2. 提供将其转换为 
    prek.toml
    的选项，以使用 prek 专属功能（glob patterns、
    repo: builtin
    ）
  3. 在相应 hooks 受支持的情况下，将 
    repo: https://github.com/pre-commit/pre-commit-hooks
    替换为 
    repo: builtin

What You Don't Do

不执行的操作

  • Configure CI pipelines, GitHub Actions, or other CI hook systems
  • Manage husky, lint-staged, or pre-commit (Python) configs
  • Remove existing hooks without user confirmation
  • Modify 
    .pre-commit-config.yaml
    directly — only generates 
    prek.toml
  • 配置 CI pipelines、GitHub Actions 或其他 CI hook 系统
  • 管理 husky、lint-staged 或 pre-commit（Python）配置
  • 未经用户确认就删除现有 hooks
  • 直接修改 
    .pre-commit-config.yaml
    ——只生成 
    prek.toml

Gotchas

注意事项

  • Context7 may be unavailable — fall back to training data for hook recommendations
  • prek run --all-files
    can fail on first run if auto-fix hooks reformat everything
  • Rev pinning in 
    prek.toml
    goes stale — recommend periodic updates
  • prek install
    needs write access to 
    .git/hooks/
    — fails in worktrees with shared hooks
  • Context7 可能不可用——回退到训练数据中的 hook 推荐
  • 首次运行 
    prek run --all-files
    时，如果自动修复 hooks 重新格式化所有内容，可能会失败
  • prek.toml
    中固定的 
    rev
    会过时——建议定期更新
  • prek install
    需要对 
    .git/hooks/
    的写权限——在共享 hooks 的 worktree 中会失败