blog.dopana

返回

在日常团队协作或文档维护中,确保每次提交前的代码规范和文档排版一致性至关重要。无需依赖庞大的第三方 npm 库,直接利用 Git 原生 Hooks 配合 core.hooksPath 即可搭建一套零依赖的高效提交流程。

存在文件无存在文件无存在文件无存在语法错误校验通过开发者执行 git commit -m '...'触发 .githooks/pre-commit 脚本1. 检查暂存区 Markdown 文件(.md, .mdx)执行 agent-md format自动 git add 变更2. 检查暂存区代码文件(.ts, .tsx, .astro...)执行 bun lint (ESLint)自动 git add 变更3. 检查暂存区文档与图表执行 bun lint:mermaid (maid)提交成功 ✅中断提交 ❌需修复错误后重试

为什么选择原生 Git Hook 而非 Husky?#

Git 原生 Hook (core.hooksPath)Husky 方案需安装 npm 依赖包增加 node_modules 体积依赖 Node.js 外部运行封装.githooks/ 目录下单个 Shell 脚本零依赖 (Zero Dependencies)天然跟随 Git 仓库版本管理
评估维度Husky / 第三方工具Git 原生 Hook (core.hooksPath)
依赖引入需安装额外 npm 包0 依赖
执行效率Node.js 封装启动有延迟Shell 脚本毫秒级启动 (<10ms)
团队共享支持支持(直接跟随 Git 仓库提交)

完整 Pre-commit 脚本实现#

在 .githooks/pre-commit 中添加以下代码:

核心逻辑解析#

1. 借助 git diff --cached 仅处理暂存区文件#

Git 暂存区 (Staged Area)git diff --cached --name-only--diff-filter=dgrep -E '\\.(后缀)$'目标处理文件列表
  • --cached:仅检查已被 git add 的暂存区文件,避免全量扫描浪费性能。
  • --diff-filter=d:排除已删除的文件,防止脚本尝试读取不存在的文件报错。
  • set -e:遇到任何检查失败立即终止流程,阻止错误代码入库。

2. 自动重新暂存(Re-stage)#

当格式化工具(如 agent-md 或 eslint --fix)修复了文件内容后,脚本通过 git add "$file" 将最新修改直接打入本次提交中,无需开发者再次手动添加。

项目中配置自动启用#

在 package.json 中配置 prepare 脚本:

{
  "scripts": {
    "prepare": "git config core.hooksPath .githooks",
    "lint": "eslint --fix 'src/**/*.{js,ts,jsx,tsx,astro}'",
    "lint:mermaid": "maid docs/ src/"
  }
}
json

添加执行权限并初始化:

chmod +x .githooks/pre-commit
bun run prepare
bash

总结#

只需一个简洁的 Shell 脚本,即可实现:

  • Markdown 文档自动格式化排版。
  • TypeScript / Astro 源码 ESLint 自动修正。
  • Mermaid 架构图语法准确性校验。

参考文献#