gitru：一个由 Rust 打造的零依赖 Git 提交信息校验工具

gitru 基于 Git 的commit-msgHook 实现用于在提交阶段自动校验提交信息格式。在团队协作开发中规范的 Git 提交信息是代码追溯、版本管理、自动生成变更日志的基础。但现实往往是人工约束容易遗漏手动配置 Hook 繁琐提交信息格式随心所欲生成 changelog 时异常痛苦因此必须由工具来保证提交信息的规范性。市面上已有不少成熟工具但大多基于 Node.js / Python / Shell 实现。问题是只是想校验一个字符串却要先安装 Node 或 Python版本不一致可能导致各种奇怪的问题国内下载依赖速度慢甚至失败安装一个工具可能要拉下一堆包属于“操作一大堆却还没开始进入正题”。这些对普通开发者尤其是新手并不友好。当然这并不是否定这些工具。相反它们非常优秀本项目开发过程中也使用了著名的pre-commit。与这些成熟工具相比gitru 甚至连 hello-world 都算不上只是一个更轻、更简单的选择。基于以上考虑再加上 Rust 非常适合编写 CLI 工具于是就有了gitru。✨ 项目特点Rust 编写零依赖二进制分发下载即可运行无需 Node、Python 或虚拟环境。虽然我不想把“Rust 编写”当成卖点免得被误会成 Rust 传教士但和其他成熟工具相比这确实是 gitru 少数能拿得出手的特点之一。⚙️TOML 格式自定义规则简单、清晰、易读、易维护。⏭️支持通过关键字跳过校验适用于自动化提交、紧急修复等场景。支持中文提交信息校验不会误判中文标点对中文开发者更友好。错误信息带颜色输出更直观、更易读。支持 Footer 关键字拼写校验Spell Check当提交信息疑似拼写错误时gitru 会自动检测并给出友好提示避免因拼写错误导致自动化流程失效。(当然这部分依赖算法和用户配置体验远不如当下的ai) Conventional Commits 简介在介绍 gitru 的使用前必须先了解业内广泛采用的提交规范 ——Conventional Commits。它定义了提交信息的结构type[optional scope]: subject [optional body] [optional footer(s)]其中type必填如feat、fix用于分类scope可选如core、ui用于描述影响范围!可选表示破坏性变更subject必填简短描述本次变更body可选详细说明footer可选如 BREAKING CHANGE、Closes #123gitru 就是基于此规范实现的并允许你通过配置文件进行自定义。 安装 gitru你可以通过三种方式安装方式一直接下载二进制文件推荐前往 GitHub Releases下载对应平台的压缩包解压后放到任意目录加入 PATHLinux / macOS 可能需要执行权限方式二通过 cargo 安装需 Rust 环境cargoinstallgitru方式三本地编译gitclone https://github.com/xiyixiaodao/gitru.gitcdgitrucargoinstall--path.验证安装gitru--version 使用方法一键初始化以下命令会同时安装 Hook 并生成配置文件gitru ii commit-msg它等价于gitruinstallcommit-msg gitru init commit-msg如果文件已存在可强制覆盖gitru ii commit-msg-f卸载 Hookgitru uninstall commit-msg然后手动删除.commit-msg-rule.toml。⚙️ 自定义校验规则gitru 的核心是配置文件.commit-msg-rule.toml。你只需要修改它就能完全定制校验逻辑。为什么选择TOML而不是 YAMLYAML 结构依赖缩进容易错位.yaml/.yml后缀容易混淆TOML 更简单、可读性更强对新手更友好即使你不懂 TOML也完全不影响使用。 配置文件示例下面是 gitru 初始化后生成的配置文件部分注释已去除# ╔═════════════════════════════════════════════════╗ # ║ COMMIT FORMAT TEMPLATE ║ # ╠═════════════════════════════════════════════════╣ # ║ type(optional scope): subject ║ # ║ ║ # ║ [optional body] ║ # ║ ║ # ║ [optional footer] ║ # ║ - BREAKING CHANGE: xxxxx ║ # ║ - Closes #issue ║ # ╚═════════════════════════════════════════════════╝ [global] version 1.0.0 enable_validation true skip_validation_words [--no-verify, SKIP] [header.type] allowed_types [feat, fix, docs, style, refactor, test, chore, ci] [header.scope] required false allowed_scopes [core, cli, ui, docs, test] [header.subject] spaces_after_colon 1 forbid_trailing_period true min_length 2 max_length 72 [body] required false min_blank_lines_before_body 1 forbid_trailing_whitespace true min_line_length 2 max_line_length 72 [footer] start_key_words [BREAKING CHANGE, Closes, Fixes, Signed-off-by] min_blank_lines_before_footer 1 min_line_length 2 max_line_length 72 forbid_trailing_whitespace true [footer.start_key_words_spellcheck] enable true threshold 0.7 配置项详解下面对关键配置项进行说明按模块划分。1. 全局配置global控制 gitru 的整体行为[global] version 1.0.0 enable_validation true skip_validation_words [--no-verify, SKIP]version: 用于以后大版本变更升级区分当前没有区别。enable_validation是否启用校验skip_validation_words提交信息第一行完全匹配时跳过校验2. Header 校验Header 是最重要的部分包含type(scope): subject2.1 type 校验[header.type] allowed_types [feat, fix, docs, style, refactor, test, chore, ci]避免出现update、tmp、aaa等无意义 type让团队提交类型统一让 changelog 自动生成更准确⚠不允许为空数组若不需要 type 校验请注释掉整个字段。提交示例校验通过feat: add login API校验失败#错误示例1 update: change UI layout #提示 error: commit type update is not in the allowed list, allowed types are [feat, fix, docs, style, refactor, test, chore, ci] #错误示例2 feats: add login API #提示 error: unknown commit type feats help: did you mean feat? (similarity 0.80) note: allowed types: [feat, fix, docs, style, refactor, test, chore, ci]2.2 scope 校验[header.scope] required false allowed_scopes [core, cli, ui, docs, test]required true→ 必须提供 scoperequired false→ 可选若提供 scope必须在 allowed_scopes 中⚠ allowed_scopes 不允许为空数组若不需要校验请注释掉整个字段。2.3 subject 校验[header.subject] spaces_after_colon 1 forbid_trailing_period true min_length 2 max_length 72限制冒号后空格数量(默认为推荐的1个建议不要修改)禁止句号结尾(包含英文句号和中文句号)限制 subject 长度3. Body 校验[body] required false min_blank_lines_before_body 1 forbid_trailing_whitespace true min_line_length 2 max_line_length 72默认可选body和header之间的空行数量(不建议修改)禁止行尾出现多余空格限制 body每一行的长度4. Footer 校验[footer] start_key_words [BREAKING CHANGE, Closes, Fixes, Signed-off-by]footer部分的起始关键字支持关键字拼写检查[footer.start_key_words_spellcheck] enable true threshold 0.7提交示例feat: test footer Close: #123错误提示error: footer keyword appears misspelled: Close → Closes similarity 0.83 (threshold 0.70)⭐ gitru 的两大特色能力1. 跳过校验Skip Validation虽然提交信息规范非常重要但在实际开发中总会遇到一些必须绕过校验的场景这些提交往往不需要遵循团队的 commit 规范甚至无法遵循。因此gitru 必须提供一种安全、明确、可控的方式来跳过校验。在 Git 生态中常见的跳过校验方式有三种①命令行参数git commit --no-verifyGit 原生支持gitcommit --no-verify它会跳过所有 Hook包括commit-msgpre-commitprepare-commit-msgpost-commit②IDE 设置跳过 Hook例如JetBrains 系列IDEA / PyCharm / RustRoverVSCode不同IDE的设置不一致有的需要设置中默认开启才会有对应操作比如VSCode有的选择跳过后如果忘记手动选回来后续校验也会继续跳过。③gitru 的方式提交信息首行关键字gitru 允许通过提交信息第一行完全匹配关键字来跳过校验注意关键字可在配置文件中配置但是严格区分大小写(当然如果只是大小写不一致会有报错信息准确提示)示例SKIP fix: hotfix production issue或--no-verify feat: auto commit from script默认配置下以上提交都会直接跳过所有校验并且在最终生成的校验信息中去除首行关键字。2. 拼写检测Spell Check由于规范约定缘故body可选中间可有空行footer也是可选的所以很难区分二者。gitru采用了footer配置关键字来区分。这样一来footer校验严重依赖用户输入的单词而人是最靠不住的所以尽可能做点保障校验用户是否拼写错误。检测 footer 关键字是否拼写错误避免Clsoe、Fixex这种低级错误导致自动化流程失效使用相似度算法默认阈值 0.7当检测到疑似拼写错误时会阻止提交并给出友好提示如果用户确认自己没错就可以使用上一步提供的方法跳过校验强制提交。footer提取关键字依赖:分割。由于footer部分自由度太高目前没想到完美的校验方法好在我们大部分时间用到的是header和body校验。 总结gitru 的目标不是取代现有工具而是提供一个更轻量更简单更易安装更适合非 Node/Python 项目的 commit-msg 校验方案。如果你在使用过程中有任何建议或问题欢迎在 GitHub 提 issue一起让这个小工具变得更好。