prek 内置钩子完全指南repo: builtin 与自动快速路径fast path实战解析【免费下载链接】prek⚡ A fast Git hook manager written in Rust, designed as a drop-in alternative to pre-commit, reimagined.项目地址: https://gitcode.com/GitHub_Trending/pr/prekprek 是一款用 Rust 编写的快速 Git Hook 管理器作为 pre-commit 的 drop-in 替代品。本文将系统讲解 prek 的两类内置钩子使用方式——通过repo: builtin直接选用 Rust 原生钩子以及针对 pre-commit-hooks 仓库的自动快速路径Automatic Fast Path并结合源码剖析其底层实现。读完本文你将掌握如何在prek.toml与.pre-commit-config.yaml中配置内置钩子、如何利用快速路径在保持上游配置兼容的同时获得原生性能、如何按需回退到远端仓库实现以及全部 29 个内置钩子的支持参数、默认值与行为差异。什么是 prek 内置钩子prek 内置了一批Rust 原生的热门钩子实现目标是提供更高的运行速度与更低的开销——无需为每个钩子启动 Python 解释器、创建虚拟环境钩子本身以库函数形式在 prek 进程内直接执行。相关的完整说明见 docs/built-in-hooks.md每个钩子的详细参数与行为见 docs/reference/built-in-hooks.md。内置钩子有两种激活途径repo: builtin直接选择在配置里声明repo: builtin按钩子 ID 选用自动快速路径保留可用的远端钩子配置来自https://github.com/pre-commit/pre-commit-hooks由 prek 自动用内置 Rust 实现替换执行。两种方式的核心差异对比如下摘自原文档| 对比项 |repo: builtin| 自动快速路径 | | -- | -- | -- | | 配置仍可被上游pre-commit使用 | 否 | 是 | | 远端仓库与 manifest | 不使用 | 在固定rev处克隆 | | 可用于回退的环境 | 不需要 | 有 | | 首次准备是否需要网络 | 否 | 是 | | 如何退出该模式 | 用远端或本地钩子替换repo: builtin| 设置钩子声明的 language或设置PREK_NO_FAST_PATH1|注意当行为细节重要时请查阅实现说明。Rust 实现的目标与上游钩子一致但在参数、默认值或边界情况上可能存在文档化差异。请在 内置钩子参考 中查看对应条目若要对比行为可关闭快速路径并运行固定 rev 的原始实现。方式一通过 repo: builtin 直接使用内置钩子在配置中添加repo: builtin并按 ID 选择钩子即可。两种配置文件格式等价 prek.tomltoml [[repos]] repo builtin hooks [ { id trailing-whitespace }, { id check-added-large-files }, ] .pre-commit-config.yamlyaml repos: - repo: builtin hooks: - id: trailing-whitespace - id: check-added-large-files 查看当前版本捆绑的内置钩子使用以下命令列出你所安装的 prek 版本捆绑的全部内置钩子含 ID、描述与支持的参数帮助prek util list-builtins该命令支持--output-format参数输出 JSON 格式便于脚本化处理其余通用选项如--config、--quiet、--verbose等与 prek 其他命令一致参见 docs/reference/cli.md。其实现位于 crates/prek/src/cli/list_builtins.rs它遍历BuiltinHooks枚举的所有变体通过BuiltinHook::from_id获取钩子元数据并调用flags_help()渲染每个钩子的 clap 参数帮助。配置约束源码级确认从配置解析源码 crates/prek/src/config/repo.rs 可以看到repo字段取值为builtin时被解析为BuiltinRepo并且不允许出现rev字段会报错rev is not allowed for builtin repos。此外参考文档明确指出repo: builtin下不允许设置entrylanguage必须是system省略language也是合法的。所有内置钩子的entry、name、description、types、stages等元数据都由 crates/prek/src/hooks/builtin_hooks/mod.rs 中的BuiltinHook::from_id统一生成。内置钩子不会创建运行环境测试 crates/prek/tests/builtin_hooks.rs 中的builtin_hooks_not_create_env验证了关键特性使用repo: builtin运行end-of-file-fixer后prek 的 hooks 目录中不会创建任何钩子环境断言hooks_dir.len() 0钩子以纯 Rust 代码在 prek 进程内运行这正是它免网络、免环境准备的原因。方式二使用自动快速路径对于来自https://github.com/pre-commit/pre-commit-hooks且被支持的钩子prek 会自动运行内置实现。这样你的既有远端配置可以继续兼容上游 pre-commitrepos: - repo: https://github.com/pre-commit/pre-commit-hooks # 启用快速路径 rev: v6.0.0 # 仅用于 manifest 读取与回退不参与快速路径判定 hooks: - id: trailing-whitespace关于rev的重要说明rev字段不参与快速路径的检测。它仍然决定 prek 读取的 manifest以及在回退场景下使用的仓库实现版本。注意在此模式下prek仍然会克隆仓库并创建环境例如 Python venv以保证完全的兼容性与回退能力。但实际钩子执行会绕过该环境直接运行原生 Rust 代码。快速路径的触发判定源码级剖析在 crates/prek/src/hooks/mod.rs 中fast_path_hook函数严格按以下条件判定是否走快速路径NO_FAST_PATH未设置——该静态变量由PREK_NO_FAST_PATH环境变量初始化定义见 crates/prek-consts/src/env_vars.rs钩子的language未被用户显式覆盖!hook.language_overridden钩子必须来自远端仓库Repo::Remote仓库 URL 必须精确等于https://github.com/pre-commit/pre-commit-hooks见 crates/prek/src/hooks/pre_commit_hooks/mod.rs 中的is_pre_commit_hooks目前仅精确匹配该字符串钩子 ID 能解析为PreCommitHooks枚举变体。命中后prek 会输出一条 debug 日志提示正在使用捆绑的 Rust 实现、行为可能与原实现有差异并建议如何回退设置language或PREK_NO_FAST_PATH1。而pretty-format-json在枚举中有明确注释——故意不加入自动快速路径直到其与上游 Python 行为的一致性覆盖足够广以免默认替换不可信源码 crates/prek/src/hooks/pre_commit_hooks/mod.rs 第 123–126 行注释。除快速路径清单之外的钩子仍走标准执行方式。回退到仓库实现方式一针对单个钩子显式设置该钩子声明的 language强制使用固定 rev 的仓库实现repos: - repo: https://github.com/pre-commit/pre-commit-hooks rev: v6.0.0 hooks: - id: check-yaml language: python # 使用固定 rev 的仓库实现方式二针对一次调用的全部钩子设置环境变量PREK_NO_FAST_PATH1 prek run环境变量说明PREK_NO_FAST_PATH在 docs/reference/environment-variables.md 中有完整条目。它默认不设置设置后所有本次调用的快速路径判定直接返回None源码见 crates/prek/src/hooks/mod.rs 第 74、81–85 行。这也正是 docs/benchmark.md 中对比实验的做法先设置PREK_NO_FAST_PATH1运行原始 Python 钩子再移除该变量让快速路径生效从而量化原生实现的性能差异。在调试时参见 docs/debugging.md也可以用它精确复现上游行为PREK_NO_FAST_PATH1 prek run check-yaml --all-files支持的钩子清单repo: builtin支持以下钩子完整参数与行为见 内置钩子参考其中带 ✅ 标记的钩子同时支持自动快速路径✅trailing-whitespace裁剪行尾空白。✅check-added-large-files阻止巨型文件被提交。✅check-case-conflict检查大小写不敏感文件系统上的文件名冲突。✅check-illegal-windows-names检查 Windows 上无法创建的非法文件名。✅end-of-file-fixer确保文件为空或以且仅以一个换行符结尾。✅file-contents-sorter对指定文件的行排序默认按字母序。✅requirements-txt-fixer对 requirements.txt 条目排序。✅fix-byte-order-marker移除 UTF-8 字节序标记BOM。✅forbid-new-submodules阻止新增 Git 子模块。✅check-json校验 JSON 语法。check-json5校验 JSON5 语法仅repo: builtin。check-jsonc校验 JSONC 语法仅repo: builtin。pretty-format-json检查/格式化 JSON 排版仅repo: builtin快速路径暂未启用。✅check-toml校验 TOML 语法。✅check-vcs-permalinks确保 VCS 链接为 permalink。✅check-yaml校验 YAML 语法。✅check-xml校验 XML 语法。deny-filename-pattern文件名匹配正则则失败仅repo: builtin。deny-pattern文件内容匹配正则则失败仅repo: builtin。require-filename-pattern文件名未匹配正则则失败仅repo: builtin。require-pattern文件内容未匹配正则则失败仅repo: builtin。✅mixed-line-ending替换或检查混合行尾。✅check-symlinks检查指向空目标的符号链接。✅destroyed-symlinks检测被替换为普通文件、内容为原符号链接目标路径的情况。✅check-merge-conflict检查合并冲突标记。✅detect-private-key检测私钥的存在。✅no-commit-to-branch保护特定分支免遭直接提交。✅check-shebang-scripts-are-executable确保带 shebang 的非二进制脚本可执行。✅check-executables-have-shebangs确保非二进制可执行文件带 shebang。通用配置说明与 pre-commit 一样通过args: [...]配置参数。对repo: builtinentry不允许language必须是system省略language也合法。部分钩子是fixer会修改文件与 pre-commit-hooks 一致它们通常在被修改后返回非零退出码让你重新运行提交。通用配置示例repos: - repo: builtin hooks: - id: trailing-whitespace args: [--markdown-linebreak-extmd] - id: check-added-large-files args: [--maxkb1024]钩子参考参数、默认值与行为差异格式化与修复类trailing-whitespace裁剪每行行尾空白。支持参数与pre-commit-hooks兼容--markdown-linebreak-extext可重复 / 逗号分隔对给定扩展名的文件保留 Markdown 硬换行行尾两个空格。用--markdown-linebreak-ext*把所有文件都当作 Markdown 处理。--charschars只裁剪指定字符集而非全部行尾空白。示例args: [--chars, \t]空格 制表符。注意事项--markdown-linebreak-ext的值只能是扩展名不允许路径分隔符。实现细节源码 crates/prek/src/hooks/pre_commit_hooks/fix_trailing_whitespace.rs 展示了其实现逻辑——按行使用split_inclusive切分先检测并剥离行尾\n/\r\n/\r在 Markdown 模式下识别并保留恰好的两空格硬换行MARKDOWN_LINE_BREAK b 再按--chars裁剪未指定--chars时用trim_ascii_end。扩展名匹配是大小写不敏感的eq_ignore_ascii_case。它的单元测试覆盖了 CRLF 处理、无效 UTF-8 文件、Unicode 裁剪字符、*通配扩展名等边界场景且能正确处理仅含空白行不触发 Markdown 硬换行保留的细节。fixer 在发生修改时返回退出码 1 并输出Fixing file。end-of-file-fixer确保文件以且仅以一个换行符结尾。无参数。行为细节空文件保持不变。只含换行符的文件会被截断为空。文件无末尾换行时追加一个\n即使文件其余部分用 CRLF。文件有多个末尾换行时缩减为恰好一个行尾。file-contents-sorter对每个匹配文件中的非空行排序并在顺序变化时重写文件。支持参数--ignore-case按 ASCII 大小写折叠排序与--unique互斥。--unique排序并去重与--ignore-case互斥。行为细节排序前移除空行与纯空白行重写文件时行尾统一为\n与上游一致该钩子默认files: ^$即默认不匹配任何文件必须显式配置files:指定目标repos: - repo: builtin hooks: - id: file-contents-sorter files: ^requirements(-dev)?\.txt$源码中对应files: Some(FilePattern::Never)的默认值见 crates/prek/src/hooks/builtin_hooks/mod.rs。requirements-txt-fixer按大小写不敏感的需求名对 Pythonrequirements*.txt与constraints*.txt条目排序。行为细节默认文件模式为(requirements|constraints).*\.txt$。排序时前导注释与续行保持与所属需求条目绑定文件顶部与尾部注释块保留。完全重复的条目会被合并优先保留带注释的副本。pkg-resources0.0.0与pkg_resources0.0.0条目会被移除与上游一致。它是排序器而非完整的 PEP 508 校验器与pre-commit-hooks一样使用轻量名称提取。fix-byte-order-marker移除文件开头的 UTF-8 字节序标记。无参数。注意事项只移除 UTF-8 BOMEF BB BF。pretty-format-json检查 JSON 文件排版并可选就地重写。支持参数与pre-commit-hooks兼容--autofix需要格式化时就地重写文件。--indentindent默认2每级缩进。数字表示多少个空格非数字值按字面使用如--indent\t使用制表符。--no-ensure-ascii保留非 ASCII 字符为 UTF-8而不是转义成\uXXXX。--no-sort-keys保持原始键顺序而不是排序对象键。--top-keysk1,k2,...在每个 JSON 对象中将指定键按给定顺序移到最前。重复键名只有第一个生效。剩余键在前缀之后未设--no-sort-keys时按排序排列。该规则对嵌套对象同样递归生效不限于根对象。注意事项该钩子目前仅能通过repo: builtin使用自动快速路径替换上游 Python 实现暂被禁用直到一致性覆盖更广重写后的文件始终使用 LF\n行尾且以恰好一个末尾换行结束。mixed-line-ending替换或检查混合行尾。支持参数与pre-commit-hooks兼容另加一种模式--fixmode默认autoauto替换为文件中出现最多的行尾。no仅检查不修改文件。lf转换为 LF\n。crlf转换为 CRLF\r\n。cr转换为 CR\r——prek 额外提供的模式。注意事项空文件与二进制文件含 NUL会被跳过。上游提示强制lf/crlf时可能受 git 的 CRLF 转换设置如core.autocrlf影响而行为不如预期。语法校验类check-json尝试加载全部 JSON 文件以验证语法。无参数。差异/注意事项本实现拒绝重复对象键报duplicate key ...解析器禁用了默认递归深度限制并对深层嵌套 JSON 采用栈友好的释放策略。check-json5尝试加载全部 JSON5 文件以验证语法。无参数。差异/注意事项本实现拒绝重复对象键报duplicate key ...。实现位于 crates/prek/src/hooks/builtin_hooks/check_json5.rs。check-jsonc检查.jsonc文件的语法。若 JSONC 存于.json文件如tsconfig.json需覆盖默认文件类型过滤repos: - repo: builtin hooks: - id: check-jsonc types: [json] files: (^|/)tsconfig\.json$ args: [--allow-trailing-commas]支持参数--allow-trailing-commas——允许对象与数组中的尾随逗号默认拒绝。差异/注意事项本实现拒绝重复对象键报duplicate key ...。实现位于 crates/prek/src/hooks/builtin_hooks/check_jsonc.rs。check-toml尝试加载全部 TOML 文件以验证语法。无参数。注意事项文件必须是合法 UTF-8非法 UTF-8 会报错单个文件可能报告多条解析错误。check-yaml尝试加载全部 YAML 文件以验证语法。支持参数与pre-commit-hooks部分兼容-m、--allow-multiple-documents别名--multi允许 YAML 多文档语法---。--disallow-unknown-tags拒绝无法识别的 YAML 标签。--unsafe只解析 YAML 语法而不加载。隐含--allow-multiple-documents。行为/注意事项默认允许无法识别的 YAML 标签——这与固定 rev 的pre-commit-hooks实现不同上游在加载时会拒绝。如需对齐上游行为请使用--disallow-unknown-tags。check-xml尝试加载全部 XML 文件以验证语法。无参数。注意事项空文件视为非法 XML存在document element 之后的多余内容多个顶层根时失败。文件名与内容模式匹配类这四类钩子的正则使用Rustregex语法。标准files、exclude与类型过滤决定哪些项目相对路径被检查。deny-filename-pattern当任一选中文件的**最终路径分量basename**匹配配置的正则时失败提供多个模式时匹配任何一个即失败。支持参数PATTERN...必填位置参数正则。模式以-开头时需用--分隔。-i、--ignore-case所有模式大小写不敏感匹配。每个匹配文件报告一次path: filename matches a denied pattern。测试 crates/prek/tests/builtin_hooks.rs 中的deny_filename_pattern_hook_matches_only_basename验证了它只匹配 basenamedocs/README.md会被readme模式命中而README/guide.md不会。repos: - repo: builtin hooks: - id: deny-filename-pattern name: disallow spaces in filenames args: [\s]deny-pattern当任一选中文本文件匹配配置的正则时失败匹配任一模式即失败。支持参数PATTERN...必填位置参数正则。模式以-开头时需用--分隔。-i、--ignore-case大小写不敏感。-m、--multiline把每个文件作为整体搜索^/$匹配行边界.匹配换行该模式会将每个选中文件读入内存。默认逐行报告为path:line:contents一行匹配多个模式只报告一次。--multiline模式下报告每个文件最早的匹配path:start-line:matched-block。repos: - repo: builtin hooks: - id: deny-pattern name: disallow wildcard imports args: [^\s*#import\s.:\s*\*] files: \.typ$require-filename-pattern当任一选中文件的 basename不匹配至少一个配置正则时失败。这是逐文件要求每个选中 basename 都必须匹配不同 basename 可以匹配不同模式。支持与deny-filename-pattern相同的位置PATTERN...与-i/--ignore-case参数匹配采用搜索语义需整体匹配时请使用^与$。未匹配文件报告为path: filename does not match any required pattern。repos: - repo: builtin hooks: - id: require-filename-pattern name: python tests naming args: - ^test_.*\.py$ - ^__init__\.py$ - ^conftest\.py$ files: (^|/)tests/.\.py$require-pattern当任一选中文本文件不匹配至少一个配置正则时失败。这是逐文件要求每个文件都必须匹配不同文件可以匹配不同模式。支持与deny-pattern相同的位置PATTERN...、-i/--ignore-case与--multiline参数。未匹配文件报告为path: no pattern matched。repos: - repo: builtin hooks: - id: require-pattern name: require a copyright notice args: [--ignore-case, copyright] files: \.(rs|py)$以上四个钩子共用的参数解析与匹配逻辑集中在 crates/prek/src/hooks/builtin_hooks/pattern.rs。平台兼容类check-case-conflict检查在大小写不敏感文件系统如 macOS / Windows上会冲突的路径。无参数。注意事项检查范围包含父目录以捕获目录级别的大小写冲突。check-illegal-windows-names检查 Windows 上无法创建的文件名。无参数。行为报告含 Windows 保留设备名的文件名如CON、PRN、AUX、NUL、COM1、LPT1。报告含 Windows 禁止字符的文件名、、:、、\、|、?、*及控制字符。报告以尾部.或空格结尾的路径段。该钩子的默认files过滤使用源码中预编译的ILLEGAL_WINDOWS_PATTERN正则见 crates/prek/src/hooks/builtin_hooks/mod.rs。Git 相关类check-added-large-files阻止巨型文件被提交。支持参数与pre-commit-hooks兼容--maxkbN默认500允许的最大文件大小KiB。--enforce-all检查所有匹配文件而不只是暂存新增文件。注意事项默认只检查暂存为新增的文件通过 git attributes 配置了filterlfs的文件会被跳过。forbid-new-submodules阻止新增 Git 子模块。无参数。行为已存在的子模块允许只报告被检查变更中新增的子模块默认检查暂存变更当PRE_COMMIT_FROM_REF与PRE_COMMIT_TO_REF同时设置时检查对应 revision 范围。check-merge-conflict检查合并冲突标记。支持参数与pre-commit-hooks兼容--assume-in-merge即使未检测到合并/rebase 状态也允许运行该钩子。注意事项默认在非合并/rebase 状态下直接成功退出仅当冲突标记出现在行首时检测检测标准冲突块、、与 diff3 祖先标记|||||||只有在前置之后才报告避免 rST 标题等内容的误报。no-commit-to-branch保护特定分支免遭直接提交。支持参数与pre-commit-hooks兼容-b、--branch branch可重复默认main、master。-p、--pattern regex可重复。注意事项该钩子默认配置为always_run: true且不接受文件名因此files、exclude、types等会被忽略除非显式设置always_run: falseHEAD 处于 detached无当前分支状态时钩子不执行。源码层面其pass_filenames为PassFilenames::None、always_run为Some(true)见 crates/prek/src/hooks/builtin_hooks/mod.rs。check-symlinks检查指向空目标的符号链接。无参数。注意事项依赖文件系统的符号链接支持Windows 上符号链接的创建与检测可能受权限影响。destroyed-symlinks检测被暂存为普通文件、但其HEAD版本是符号链接的文件——通常发生在不支持符号链接的环境下检出仓库时。无参数。注意事项与上游pre-commit-hooks一致只检查git status --porcelainv2报告的已跟踪条目比较暂存文件与原始符号链接目标路径时刻意忽略仅由尾部 ASCII 空白空格、制表符、换行/CRLF 转换构成的差异因为这类差异常由格式化钩子引入。安全类detect-private-key检测私钥的存在。无参数。注意事项这是对常见 PEM/密钥头的启发式子串扫描如BEGIN RSA PRIVATE KEY、BEGIN OPENSSH PRIVATE KEY、BEGIN PGP PRIVATE KEY BLOCK等可能产生误报与漏报。脚本与可执行文件类check-executables-have-shebangs检查非二进制可执行文件是否带有正确的 shebang。无参数。注意事项检查刻意保持轻量——只验证文件以#!开头在文件系统不跟踪可执行位的系统上prek 会参考 git 的暂存 mode bits。check-shebang-scripts-are-executable检查带 shebang 的非二进制文件是否被标记为可执行。无参数。注意事项检查刻意保持轻量——只验证文件以#!开头为兼容不跟踪可执行位的文件系统prek 会参考 git 的暂存 mode bits。VCS 链接类check-vcs-permalinks确保指向 VCS 网站的链接是 permalink。支持参数与pre-commit-hooks兼容--additional-github-domaindomain可重复在默认github.com之外增加要检查的 GitHub 风格域名。行为/注意事项标记形如https://domain/owner/repo/blob/branch/...#L...的链接当branch已是 4–64 位十六进制提交哈希时不算非 permalink内置与快速路径实现目前遵循上游钩子的 GitHub 系匹配行为。源码视角内置钩子的执行链路了解执行链路有助于在生产中判断行为与排查问题。核心分发逻辑在 crates/prek/src/hooks/builtin_hooks/mod.rs 的BuiltinHooks::run它根据钩子 ID 将调用路由到对应的 Rust 实现函数如fix_trailing_whitespace::run、check_yaml::run并统一包装成HookFuture异步任务。几个值得注意的实现事实参数解析带参数的钩子通过 clap 声明Args结构如 crates/prek/src/hooks/pre_commit_hooks/fix_trailing_whitespace.rs 的Args由 crates/prek/src/hooks/pre_commit_hooks/mod.rs 的parse_hook_args把entry与配置的args合并后解析。这些Args同时被 crates/prek/src/cli/list_builtins.rs 的flags_help()复用来渲染prek util list-builtins的参数帮助。并发执行多数逐文件检查通过run_file_checks/run_concurrent_file_checks以配置的并发度并行处理crates/prek/src/hooks/mod.rs按输入顺序合并结果显式文件名来自entry/args先串行执行再并发处理选中文件且有意保留重复与重叠。快速路径与内置路径共享实现repo: builtin与自动快速路径最终调用的是同一批 Rust 实现函数区别仅在于分发入口——前者走BuiltinHooks::run后者走PreCommitHooks::runcrates/prek/src/hooks/pre_commit_hooks/mod.rs。测试保障除前文提到的场景外crates/prek/tests/builtin_hooks.rs 还覆盖了未知钩子 ID 的报错unknown builtin hook id ...、deny-pattern的行级报告等行为各钩子实现文件内也有大量单元测试如fix_trailing_whitespace.rs对 Markdown 硬换行、CRLF、Unicode 裁剪的验证。实践建议与相关文档新项目/追求零网络与零环境开销使用repo: builtin适合离线 CI 或希望提交前准备步骤最少化的场景。需要与上游 pre-commit 保持配置兼容保留https://github.com/pre-commit/pre-commit-hooks远端配置让 prek 自动走快速路径rev仍锁定 manifest 与回退实现。行为敏感、需要逐字节对齐上游对单钩子显式设置language或整体使用PREK_NO_FAST_PATH1 prek run再对比两者输出。相关阅读内置钩子参考全部钩子的参数与行为细则。docs/reference/cli.mdprek util list-builtins等 CLI 命令参考。docs/reference/environment-variables.mdPREK_NO_FAST_PATH等环境变量。docs/configuration.md配置格式与args、files、types等通用钩子选项。docs/benchmark.md利用PREK_NO_FAST_PATH对比原生实现与上游实现的性能方法论。【免费下载链接】prek⚡ A fast Git hook manager written in Rust, designed as a drop-in alternative to pre-commit, reimagined.项目地址: https://gitcode.com/GitHub_Trending/pr/prek创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考