企业官网建设流程全解析

Lefthooktemplates配置指南：为 Git Hook 命令注入可复用占位符

【免费下载链接】lefthookFast and powerful Git hooks manager for any type of projects.项目地址: https://gitcode.com/GitHub_Trending/le/lefthook

导读

本文讲解 lefthook 的templates配置项：它允许你在run命令值中声明自定义占位符（如{dip}、{wrapper}），并在lefthook-local.yml中按环境覆盖其实际内容，从而免去逐一改写每个 job 的麻烦。读完本文，你将掌握占位符的声明与覆盖语法、与内置文件占位符（如{staged_files}）的协作方式，以及这一机制在源码中的底层替换原理，可以直接在自己的项目中落地复用。

一、templates是什么

templates是 lefthook 顶层配置项，用于为run值提供自定义替换模板。它于 lefthook1.10.8版本引入，声明形式为键值对映射：

templates: <key>: <replacement>

在配置模型中，它对应Config结构体上的一个字段（见 internal/config/config.go）：

Templates map[string]string `json:"templates,omitempty" jsonschema:"description=Custom templates for replacements in run commands." mapstructure:"templates,omitempty"`

• 键（key）：你在run中引用的占位符名字，实际书写时需用花括号包裹，如{dip}。
• 值（value）：替换后实际拼入命令的字符串，可以是任意 shell 片段（如docker-compose run --rm -v $(pwd):/app service）。

配置加载完成后，run命令中的{key}会被替换为对应的 value，再交由 shell 执行。由于 value 只是普通文本拼接，替换结果支持任意合法的 shell 语法——包括命令、环境变量、管道等。

二、核心用法：通过lefthook-local.yml按环境覆盖

templates最大的价值在于：同一个团队配置（lefthook.yml）可以在不修改 job 的前提下，由各开发者用lefthook-local.yml覆盖占位符的实际内容。这在"团队使用 dip（Dev Improvement Process）包裹命令、而部分成员未安装 dip"的场景下非常实用。

团队仓库中的lefthook.yml先声明一个空模板占位：

# lefthook.yml templates: dip: # empty pre-commit: jobs: # Will run: `bundle exec rubocop -- file1 file2 file3 ...` - run: {dip} bundle exec rubocop -- {staged_files}

此时{dip}的 value 为空字符串，实际执行命令即为bundle exec rubocop -- file1 file2 file3 ...。

开发者个人再通过lefthook-local.yml提供自己的 dip 封装：

# lefthook-local.yml templates: dip: dip # Will run: `dip bundle exec rubocop -- file1 file2 file3 ...`

此后该开发者的 pre-commit 实际执行的就是dip bundle exec rubocop -- file1 file2 file3 ...。占位符与内置的{staged_files}可以自由组合，替换结果中文件列表照常展开。

需要说明的是：lefthook-local.yml的合并由配置加载器完成，顶层templates与lefthook等选项一样允许被本地配置覆盖（合并逻辑见 internal/config/loader.go）。

三、减少重复：用一个模板复用复杂前缀

当多个 job 共享同一个命令前缀时，templates也能有效消除冗余。例如团队统一通过 docker-compose 服务执行所有检查：

# lefthook.yml templates: wrapper: docker-compose run --rm -v $(pwd):/app service pre-commit: jobs: - run: {wrapper} yarn format - run: {wrapper} yarn lint - run: {wrapper} yarn test

三个 job 实际执行的命令分别是：

docker-compose run --rm -v $(pwd):/app service yarn format docker-compose run --rm -v $(pwd):/app service yarn lint docker-compose run --rm -v $(pwd):/app service yarn test

如果将来 wrapper 命令需要调整（比如更换镜像 tag 或增加挂载目录），只需修改templates中wrapper一处，所有引用它的 job 全部生效。这与把 wrapper 写死在每个run中相比，维护成本显著降低。

四、与内置占位符的协作

lefthook 的run值本身已支持一批内置占位符，例如：

• {staged_files}：暂存区文件列表（pre-commit 等钩子）
• {push_files}：待推送文件列表（pre-push）
• {all_files}：仓库全部文件
• {files}：由files选项显式指定的文件列表
• {0}/{1}等：Git 钩子附加参数（git args）

自定义模板与这些内置占位符共用同一套替换管线，因此可以在同一条命令中混合使用，如第一节的{dip} bundle exec rubocop -- {staged_files}。两者的区别在于：

• 内置文件类占位符的 value 来自 Git 状态查询，且文件名会经过 shell 转义（见 internal/run/controller/command/replacer/replacer.go 的escapeFiles）；
• 自定义模板的 value 是配置中的纯文本，不做转义，直接拼接进命令（见同文件 replacer.go 中"Only escape file templates, not custom templates"的注释逻辑）。

五、源码层面的实现原理

从源码结构看，templates的生效链路大致如下：

1. 配置解析：加载器把 YAML 中的templates映射填入Config.Templates（字段定义见 internal/config/config.go）；
2. 透传：lefthook run命令读取配置后，将cfg.Templates传入执行控制器（见 internal/command/run.go 的Templates: cfg.Templates，对应 internal/run/controller/controller.go 的选项字段）；
3. 注入 Replacer：命令构建器调用AddTemplates(b.opts.Templates)，把每个key包装成{key}形式存入替换表（见 internal/run/controller/command/build_command.go 与 internal/run/controller/command/replacer/replacer.go）；
4. 扫描与替换：Discover统计命令中出现次数并缓存替换内容，ReplaceAndSplit在切分命令（受系统最大命令长度限制）时完成最终替换（见 internal/run/controller/command/replacer/replacer.go）。

另外，setup阶段执行的命令同样支持模板替换（见 internal/run/controller/setup.go 的AddTemplates(opts.Templates)），因此templates也可用于钩子前置的setup命令。

六、验证与测试

仓库提供了针对templates的集成测试（见 tests/integration/templates.txt）：它初始化一个 Git 仓库，配置templates.message: hello，然后运行一个输出echo {message}的testjob，断言 stdout 匹配hello。这从端到端验证了占位符的解析、替换与执行全流程。

你可以通过类似方式在自己的项目中快速验证：

git init && lefthook install # 初始化并安装钩子 lefthook run test # 手动触发 test hook，观察 {message} 被替换为 hello

七、注意事项

1. 空值模板合法：templates的值允许为空字符串（如dip: # empty），此时占位符会被替换为空，命令按去掉该片段后的形态执行，这是"团队默认不包裹、个人按需覆盖"模式的关键。
2. 不做 shell 转义：自定义模板按原样拼入命令，请确保 value 中不包含意外的引号或注入内容；模板通常由团队维护，属于受信配置。
3. 不适用于 hook 名：templates仅作用于run值（以及setup命令），不会影响pre-commit等钩子键名本身。
4. 版本要求：该特性需要 lefthook1.10.8及以上版本；如需声明最低版本约束，可配合min_version配置项使用。

八、总结

templates为 lefthook 配置提供了一层轻量、可覆盖的抽象：团队把需要变化的前缀或包装命令抽象为占位符，开发者个人通过lefthook-local.yml注入本机实现，多个 job 之间的重复前缀也得以集中管理。配合内置的文件占位符与 shell 语法，它几乎可以覆盖所有"同一命令不同环境不同写法"的场景，让 Git Hook 配置保持简洁的同时不失灵活性。

【免费下载链接】lefthookFast and powerful Git hooks manager for any type of projects.项目地址: https://gitcode.com/GitHub_Trending/le/lefthook