Lefthook 本地配置指南用 lefthook-local.yml 实现个人化覆盖与团队配置隔离【免费下载链接】lefthookFast and powerful Git hooks manager for any type of projects.项目地址: https://gitcode.com/GitHub_Trending/le/lefthookLefthook 提供了一种优雅的个人化配置机制通过lefthook-local.yml在不修改团队共享配置的前提下按需覆盖、扩展甚至完全替代主配置文件。本文围绕这一机制讲解其加载优先级、合并规则、典型实战场景跳过任务、改写命令、docker 包装、仅本地使用以及源码层面的实现原理帮助你为每个仓库定制属于自己的 Git Hooks 工作流。什么是 lefthook-local.ymllefthook-local.yml是 Lefthook 的本地配置文件用于扩展和覆盖主配置lefthook.yml中的选项。它与主配置的关键区别在于主配置lefthook.yml提交到版本库被所有协作者共享本地配置lefthook-local.yml被.gitignore忽略只存在于你的工作区仅供个人使用。这意味着你可以在不打扰团队其他成员的情况下调整 Hooks 的运行方式。例如团队要求每次提交都跑全量测试而你本地希望跳过测试只做 lint或者想把命令包进 Docker 容器运行——这些都可以通过本地配置完成。提示你也可以把lefthook-local.yml加入~/.gitignore全局 gitignore这样你在每个项目里都能放心创建本地覆盖配置无需每个仓库单独忽略它。配置文件命名与查找规则从源码看Lefthook 内置了主配置与本地配置两套候选文件名internal/config/loader.go主配置候选名lefthook、.lefthook、.config/lefthook本地配置候选名lefthook-local、.lefthook-local、.config/lefthook-local两者都支持yml、yaml、json、jsonc、toml五种扩展名见 loader.go。加载时按扩展名优先级逐一遍历候选名找到第一个存在的文件即加载loadFirst见 loader.go。加载顺序与合并语义理解本地配置首先要理解 Lefthook 的三层加载流程对应Loader.LoadKoanf与LoadSecondary见 internal/config/loader.go主配置加载lefthook.yml或LEFTHOOK_CONFIG环境变量指定的配置文件extends / remotes合并主配置中声明的扩展配置与远端配置本地配置加载lefthook-local.yml作为覆盖层合并到前面得到的配置之上。在 unmarshalConfigs 中每个 Hook 都会被单独切分出来主配置中的 Hook 与本地配置中的同名 Hook 通过 addHook 合并最终main.Merge(secondary)把本地配置作为覆盖源合并进主配置。jobs 的按名合并对于jobs列表本地配置不会简单替换整个列表而是按 job 名称进行合并mergeJobsSlice见 loader.go同名 job本地配置的字段覆盖主配置中同名 job 的对应字段其余字段保留新增 job追加到列表末尾。这正是官方文档示例docs/usage/features/local.md能生效的底层原因。看这个核心示例# lefthook.yml提交进仓库团队共享 pre-commit: jobs: - name: linter run: yarn lint - name: tests run: yarn test# lefthook-local.yml被 git 忽略仅个人使用 pre-commit: jobs: - name: tests skip: true # 不想每次提交都跑测试 - name: linter run: yarn lint {staged_files} # 只对暂存文件做 lint合并后的效果是testsjob 被标记为跳过linterjob 的run被改写为只处理暂存文件——而团队其他成员不受任何影响。细节setup列表的合并语义与jobs不同本地配置中的setup会被前置拼接见 loader.go测试用例with setup instructions验证了这一顺序见 internal/config/loader_test.go。实战场景一跳过不想运行的命令本地配置最常见的用途是跳过团队配置中某些命令。得益于skip选项你既可以在本地把某个命令全局跳过也可以按 git 状态、分支等条件跳过。直接把skip覆盖为true# lefthook.yml pre-commit: commands: lint: run: yarn lint# lefthook-local.yml pre-commit: commands: lint: skip: trueskip支持更丰富的取值详见 docs/configuration/skip.mdmerge、rebase、merge-commit、ref: main指定分支、run: 命令命令返回码为 0 时跳过等这些条件同样可以在本地配置中使用。实战场景二改写 run 命令与 {cmd} 模板除了skip你还可以在本地改写run字段从而改变命令的实际执行方式。例如把主配置的命令用 Docker 包装起来执行示例来自 docs/configuration/run.md# lefthook.yml pre-commit: commands: lint: run: yarn lint scripts: good_job.js: runner: node# lefthook-local.yml pre-commit: commands: lint: run: docker run -it --rm container_id_or_name {cmd} scripts: good_job.js: runner: docker run -it --rm container_id_or_name {cmd}这里{cmd}是一个特殊模板会在合并时被替换为主配置中对应 job/command 的原始run命令。源码层面这一替换发生在addHook与mergeJobsSlice中loader.go、loader.go合并前会把本地run中的{cmd}替换为主配置的原始命令从而实现包装但不重写的效果。本地覆盖时run支持所有标准模板{staged_files}、{push_files}、{all_files}、{files}、{cmd}、{0}/{1}等 git 参数详见 docs/configuration/run.md。实战场景三添加团队配置中没有的 Hook本地配置不仅能修改已有内容还可以新增整个 Hook。官方示例docs/examples/lefthook-local.md展示了在本地追加一个post-mergeHook# lefthook.yml pre-commit: commands: lint: run: bundle exec rubocop -- {staged_files} glob: *.rb check-links: run: lychee -- {staged_files}# lefthook-local.yml pre-commit: parallel: true # 让所有命令并发执行 commands: lint: run: docker-compose run backend {cmd} # 用 docker-compose 包装原命令 check-links: skip: true # 跳过链接检查 # 新增一个本地独有的 Hook post-merge: files: git diff-tree -r --name-only --no-commit-id ORIG_HEAD HEAD commands: dependencies: glob: Gemfile* run: docker-compose run backend bundle install合并后 Lefthook 实际使用的配置等价于pre-commit: parallel: true commands: lint: run: docker-compose run backend bundle exec rubocop -- {staged_files} glob: *.rb check-links: run: lychee -- {staged_files} skip: true post-merge: files: git diff-tree -r --name-only --no-commit-id ORIG_HEAD HEAD commands: dependencies: glob: Gemfile* run: docker-compose run backend bundle install这个示例同时展示了三种覆盖能力修改 Hook 级选项parallel、改写命令{cmd}包装、跳过命令skip: true以及新增 Hook。实战场景四只有本地配置没有主配置lefthook-local.yml还可以独立使用——即使仓库中不存在lefthook.yml也能正常工作。这在你想只在自己机器上启用 Lefthook、而不强加给队友时非常有用。源码层面loadFirstMainloader.go在找不到主配置时会回退检查本地配置只要存在lefthook-local.yml加载流程就继续不会报错。相关测试用例with lefthook-local.yml only和with .lefthook-local.yml only验证了这一行为见 internal/config/loader_test.go# lefthook-local.yml仓库中没有任何 lefthook.yml pre-commit: commands: tests: run: yarn test post-commit: commands: ping-done: run: curl -x POST status.com/done此时 Hook 照常生效而团队其他成员完全没有感知。本地脚本目录source_dir_local如果你的本地配置需要引用脚本文件而不是内联命令可以配合source_dir_local选项指定本地专属的脚本目录详见 docs/configuration/source_dir_local.md# lefthook-local.yml source_dir_local: .lefthook-local/该选项默认值为.lefthook-local/见 internal/config/config.go 与 internal/config/jsonschema.json专门用于存放不纳入版本库的本地脚本文件与存放团队共享脚本的source_dir默认.lefthook区分开。注意source_dir_local是一个全局配置项即使没有主配置文件单独放在lefthook-local.yml顶层也能生效测试用例见 internal/config/loader_test.go。最佳实践小结先.gitignore再创建把lefthook-local.yml以及.lefthook-local/目录加入.gitignore避免误提交。全局 gitignore 更省心团队配置保持克制把必须执行的规范lint、格式检查放在lefthook.yml把个人偏好跳过测试、Docker 包装、额外 Hook放在lefthook-local.yml善用{cmd}模板包装命令时优先用{cmd}引用原命令而非重写整条命令减少与团队配置的漂移独立本地使用不想影响队友时可以直接只放一个lefthook-local.yml无需主配置。Lefthook 的本地配置机制把团队规范与个人自由干净地解耦主配置定义协作底线lefthook-local.yml提供个人空间两者通过按名合并、skip覆盖与{cmd}包装等规则优雅共存。【免费下载链接】lefthookFast and powerful Git hooks manager for any type of projects.项目地址: https://gitcode.com/GitHub_Trending/le/lefthook创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考