Lefthook 用于以快速、可维护的方式配置 Git 钩子。本技能聚焦于编写、调试和解释 Lefthook 配置。
一、用途
当用户提及 lefthook、lefthook.yml、lefthook install 等内容时，可使用本技能来配置、排查和维护 Git 钩子。
二、主要能力
- 根据项目生态匹配安装说明：npm、Go、Ruby、Python、Homebrew 或独立二进制文件。
- 为新建配置推荐使用 jobs；commands 和 scripts 仍然有效且常见。
- 通过
{staged_files}、{push_files}、glob、file_types、root让钩子保持快速且限定文件范围。 - 使用
lefthook validate进行语法检查，使用lefthook dump调试合并后的配置。 - 明确
lefthook install通常是一次性设置；配置变更会在每次钩子执行时读取。
三、快速查阅路径
- 需要安装说明和官方文档地图：
references/official-docs.md - 需要 CLI、配置模型、模板、合并顺序：
references/api-surface.md - 需要常见真实场景模式：
references/common-use-cases.md - 排查钩子被跳过或行为异常：
references/troubleshooting-workarounds.md - 需要可直接复制的配置：
examples/basic-lefthook.yml、examples/monorepo-jobs.yml、examples/commit-message.yml、examples/lefthook-local.yml - 需要反模式与修复：
examples/anti-patterns.md
四、推荐工作流
- 检查现有 package scripts、linters、测试命令以及当前 Git 钩子工具。
- 选择最小的有用钩子范围：通常是 pre-commit、commit-msg 和 pre-push。
- 根据是否需要分组、命名合并或外部可执行文件，选择 jobs、commands 或 scripts。
- 除非检查确实需要整个仓库，否则将工作范围限定到已更改文件。
- 仅在需要本地覆盖或共享策略时，添加
lefthook-local.yml、extends 或 remotes。
五、核心规则
- 除非工作流明确需要提示，否则优先使用确定性、非交互式钩子。
- 仅对会修改暂存文件的 pre-commit 修复器使用
stage_fixed: true。 - 记住
glob是从 Git 仓库根目录求值的，即使root改变了工作目录。 - 对于可能递归回 Git 钩子的工具，使用
LEFTHOOK=0。 - 在测试完整 Git 流程之前，使用
lefthook run <hook>直接调试某个钩子。
六、外部文档
- 文档：https://lefthook.dev/
- GitHub：https://github.com/evilmartians/lefthook
七、限制 本资料未提供 Lefthook 的收费、价格、性能指标或平台兼容性细节，相关事实暂未提供。