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

任何一个带过团队、搞过代码评审的人，应该都经历过那种时刻：打开git log，满眼都是“fix bug”“update”“修改”“提交一下”……想定位某个功能是哪次提交引入的，恨不得把作者拽过来当面问。提交信息这件事，听起来特别小，实际上每天都在消耗团队的认知成本。所以当我看到 gitru 这个项目的时候，第一反应是：终于有人愿意用正经方式处理这个“小问题”了。

gitru 是一个用 Rust 打造的零依赖 Git 提交信息校验工具，核心作用就是在 commit 产生的时候，用一套可配置的规则去检查提交信息合不合规，不合规就拒绝提交。它最适合两类人：一类是深受提交信息混乱之苦的技术负责人，想给团队立规矩；另一类是个人开发者，想对自己的提交习惯做一点约束，顺带体验一下 Rust 写 CLI 工具的思路。这篇文章我会从设计逻辑、安装配置、团队落地到踩坑记录，完整拆解这个工具，末尾还会聊一聊我在实际使用中的真实感受。

1. 为什么需要 gitru：提交信息混乱的真实代价

1.1 一行 commit message 带来的连锁问题

先说一个我自己的经历。前几年维护一个老项目，线上出了个诡异的数据问题，直觉告诉我某个模块最近被改过。我打开 git log，看到的是一堆 “fix”“update” 的模糊信息，根本判断不了哪次提交动了相关逻辑。最后只能挨个 diff，花了整整一上午才定位到一个改坏边界条件的提交。那次的教训特别深刻：写提交信息的时候省下的 10 秒，会在未来某个深夜以几十倍的时间还回来。

提交信息混乱的代价是连锁的。回滚的时候你不知道该回退到哪个版本；写 changelog 的时候你得自己从 diff 里猜意图；做 code review 的时候评审者看到 “update” 这种信息，根本没法快速判断这行改动的背景。如果团队里还有自动化发布流程，靠提交信息生成 release notes，那混乱的提交信息直接就让整个发布说明变成废纸。

所以提交信息校验这件事，本质上不是“形式主义”，而是把“人肉阅读理解”的成本前置到提交的那一刻。校验工具干的活很简单：在 commit 创建时拦住不合规的信息，逼着写作者用结构化的方式表达“这次提交做了什么、为什么做”。这比任何事后补文档的方式都高效。

1.2 现成方案为什么不够顺手

校验提交信息并不是个新需求，市面上的方案其实不少。但我在实际用下来之后，总觉得差了点什么。

最常见的做法是团队里放一个 shell 脚本，挂在commit-msghook 上。脚本的思路本身没问题，无非就是读取提交信息、正则匹配、不符合就退出非零状态码。但 shell 脚本的维护性堪忧，尤其是跨平台场景：Linux 上跑得好好的，Windows 上因为/bin/bash路径问题直接罢工。而且脚本里的规则越加越多，正则转义、引号嵌套这些细节分分钟让人崩溃。

另一种主流选择是 commitlint，它功能很全，背后有整个 Node.js 生态。但问题也出在这：为了校验一个提交信息，你得装 Node.js 环境、初始化 npm 包、装一堆传递依赖，README 都没看完，node_modules已经几百兆了。如果团队里还有人不用 Node 技术栈，为了这个工具单独装一套运行时，推广阻力非常大。

gitru 选择了完全不同的路线：Rust 编写、零依赖、单个静态编译二进制。没有运行时要求，不装 Node 也不装 Python，下载下来就能跑。这个定位让我眼前一亮——它解决的不只是“有没有规则"的问题，而是“规则能不能被低成本普及”的问题。对于工具链已经够臃肿的团队来说，少一个依赖就是少一份维护负担。

2. gitru 的核心设计：零依赖和 Rust 选型的逻辑

2.1 “零依赖”到底是怎么做到的

“零依赖”这个词现在被用得很随意，有些项目说自己零依赖，实际上只是把依赖藏得比较深。但在 Rust 项目里，零依赖是一个可以被严格验证的特性：打开项目的Cargo.toml，看[dependencies]部分是不是空的，依赖的所有 crate 都必须来自 Rust 标准库。

这意味着 gitru 不能用 regex crate 做正则、不能用 clap 做命令行参数解析、不能用 anyhow 做错误处理。这些在 Rust 生态里几乎是“标配”的库，全都得放弃。那怎么实现功能？参数解析可以用std::env::args自己处理，简单场景下完全够用；正则匹配可以退化成前缀匹配、长度限制、枚举比对、通配符匹配的集合。听起来是“退而求其次”，但提交信息这种结构化文本，本身就不需要多复杂的模式匹配，简单的规则组合反而更直观、更好维护。

零依赖带来的好处很实在。编译时间大幅缩短——Cargo 拉完依赖后的首次编译，跟从零开始的编译时间差一个数量级。二进制体积也小得多，通常只有一两兆，放哪都不占地。但我觉得最值钱的还不是这些，而是供应链风险的控制：依赖越少，被恶意代码注入的可能性就越小。一个校验提交信息的工具，理论上要接触团队的 Git 仓库数据，如果它带着一堆来路不明的传递依赖，安全性就没法保证。

2.2 Rust 写 CLI 工具凭什么体验好

Rust 这几年的声量很大，我身边不少写 Go、写 C++ 的朋友都在学。但 Rust 在 CLI 工具领域有一个其他语言很难比的卖点：静态编译 + 单文件分发。跑起来不需要虚拟机、不需要解释器、不需要把环境变量配得乱七八糟，一个二进制拷到任何同架构机器上就能直接跑。

这类工具的标杆就是 ripgrep、fd、bat。这些 Rust 社区明星工具已经证明了：Rust 写出来的命令行工具，启动速度快、内存占用低、跨平台一致性好。gitru 走的是同一条路，所以它能在没有 Node、没有 Python 的纯净环境里直接工作。对于 Git 这个本身就跨平台、分布极广的工具来说，搭配一个同样跨平台、无依赖的校验工具，体验是很顺滑的。

还有一点就是内存安全。Rust 的编译器在编译期就能挡住一大类内存错误，做这种跟 Git 仓库、文件系统打交道的工具，稳定性是刚需。你不想在周一早上 commit 的时候被一个段错误打断吧？Rust 写这类工具，本质上就是用编译器的严格换运行时的乖顺。

2.3 校验规则从哪来：Conventional Commits 的落地

gitru 这类工具的核心是校验规则。规则不是凭空定的，业界已经有一份被广泛接受的规范：Conventional Commits（约定式提交）。它把提交信息标准化成这样：

<type>[optional scope]: <description>

type是这次提交的类型，比如feat表示新功能、fix表示修 Bug、docs表示文档变更。scope是影响范围，可选的，比如feat(parser): add support for streaming。description是一句话描述，一般要求祈使句、不超过一定长度。

这套规范之所以被这么多团队采用，是因为它用统一的前缀把“意图”结构化，机器可读、人也好懂。gitru 的配置本质上就是这套规范的可定制版本：允许哪几个 type、是否必须带 scope、subject 最长几个字符、正文有没有要求。它不强制你用某种规范，而是让你先把规范定下来，然后强制执行。

我自己的经验是：规则不要一上来就设得很严。先保留几个最常用的 type，subject 长度限制也不要太苛刻，让团队先跑起来养成习惯，后面再根据实际情况收紧。

3. 从安装到第一次校验：五分钟上手 gitru

3.1 三种安装方式怎么选

gitru 的安装方式取决于你的环境。最省心的是直接下载 Release 页面里的预编译二进制，解压后放到PATH里的任意目录就行。适合有 Rust 开发环境的人，直接一行命令搞定：

cargo install gitru

装完之后用gitru --version验证一下，能正确输出版本号就说明安装成功。我个人实测下来，整个安装过程在正常网络环境下通常在几十秒到几分钟之间，体验比装一套 Node 环境快得多，也更安静——不产生node_modules，不修改全局依赖，属于“下载一个文件，完事”的轻量级方案。

提示：如果你用的是 macOS 或 Linux，记得给二进制文件加执行权限。下载完发现提示 “Permission denied” 的话，执行chmod +x gitru就好。

3.2 最小的配置文件长什么样

gitru 的配置思路不复杂，核心是在仓库根目录放一个配置文件，默认文件名通常是gitru.toml。我用一个最小可用的例子来说明：

[rules] # 允许的提交类型 types = ["feat", "fix", "docs", "refactor"] # subject 最大长度 subject_max_length = 72 # 是否必须包含类型前缀 require_type = true # 是否允许 WIP 提交 allow_wip = false # 不允许的提交词 forbidden_words = ["update", "提交", "修改"]

这个配置表达的规则是：提交信息必须以feat/、fix/、docs/、refactor/开头，冒号后面的一句话描述不能超过 72 个字符，不允许出现update这类模糊词汇。这个示例比较简单，但骨架已经立起来了。

注意到我特意建议把update这种“看起来无害”的词列入禁用列表。因为它太常被当作万金油用，一旦混进提交记录，信息熵就急剧下降。与其事后在 git log 里跟它较劲，不如在提交那一刻就把它拦住。

3.3 check 命令到底做了什么

配置好之后，gitru 的使用方式很直观。最常用的是直接传入提交信息：

gitru check "fix: correct the null pointer check in user login"

如果校验通过，命令静默退出，返回状态码 0；如果失败，它会输出具体的错误原因和修复建议，比如：

Error: subject exceeds maximum length (current: 85, max: 72)

它也可以交给 Git hook 调用，自动读取COMMIT_EDITMSG文件里的提交信息，这正好覆盖了提交时的典型场景。在 commit-msg hook 里写一行gitru check，Git 就会在每次提交时让 gitru 去“把关”，不通过直接拒绝提交。

退出的状态码这套逻辑背后是 Unix 工具的通用哲学：进程用退出码表达“是/否”，调用方可以根据退出码决定后续动作。Git 本身也是这么设计的——hook 脚本返回非零状态码，Git 就中止 commit。gitru 只是把这个约定延续下来。

4. 把 gitru 用起来：配置一份适合团队的提交规范

4.1 一套可以直接抄的团队配置

配置文件的语法只是第一步，真正难的是设计一套适合团队的规范。这里我放一份我在几个项目里都验证过的配置，你可以直接改吧改吧就用：

[rules] types = [ "feat", # 新功能 "fix", # 修复 Bug "docs", # 文档修改 "style", # 格式调整（不影响逻辑） "refactor", # 重构（不修 Bug 不加功能） "perf", # 性能优化 "test", # 测试相关 "build", # 构建系统或外部依赖变更 "ci", # CI 配置变更 "chore", # 其他杂项 "revert", # 回滚 ] subject_max_length = 72 require_type = true require_scope = false allow_wip = false [commit_headers] # 是否强制要求 header 和 body 之间有空行 require_body_separator = true

这套配置基本对齐 Conventional Commits 的官方推荐，但 type 列表是压缩过的。我特意砍掉了像types这种在大多数项目里都用不上的类型，减少团队成员的选择成本。选择太多等于没选，提交规范也是这个道理。

subject_max_length = 72这个取值的来源是 Git 社区的传统：Git 源码里的提交信息建议把标题控制在 72 字符以内，超过这个宽度，很多终端工具里显示就会折行，阅读体验大打折扣。至于require_scope = false，我的建议是刚开始时不要强制 scope，让团队先习惯“类型 + 描述”的基本结构，等大家熟练了再逐步引入 scope，这样推广阻力小很多。

4.2 接入 Git Hooks 的正确姿势

配置写好之后，下一步就是把它接到 Git 的提交流程里。我用的是 Git 自带的 hooks 机制，在.git/hooks/commit-msg里写脚本。但这带来一个问题：.git目录不会进版本库，每个开发者的本地 hook 都得手动复制，很不方便。

比较现代的解法是用core.hooksPath让 Git 指向一个受版本控制的 hooks 目录：

git config core.hooksPath .githooks

然后在仓库里创建.githooks/commit-msg文件：

#!/bin/sh gitru check "$1"

这里$1是 Git 传给 commit-msg hook 的提交信息文件名，gitru 会读取这个文件并执行校验。脚本写好之后记得加执行权限：

chmod +x .githooks/commit-msg

把.githooks目录提交到仓库里，这样每个克隆这个仓库的人，只要执行一次git config core.hooksPath .githooks，就能获得完全一致的提交校验体验。

注意：commit-msghook 的脚本必须保持轻量，不要在 hook 里跑任何可能卡住的命令，比如等待输入或请求远程接口。提交过程一旦被卡住，开发者的第一反应就是绕过 hook。

4.3 在 CI 里拦住不合规提交

本地 hook 不是万能的，总有开发者会绕过它（比如临时git commit --no-verify），也总有人在其他机器上改完直接推。所以 CI 这一道防线不能省。

以 GitHub Actions 为例，核心思路是让 CI 检查最近一次提交的提交信息是否符合规则：

name: check-commit-message on: [push] jobs: lint-commit: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Install gitru run: | # 下载预编译二进制或者通过 cargo 安装 cargo install gitru - name: Check latest commit message run: | MESSAGE=$(git log -1 --pretty=%B) gitru check "$MESSAGE"

这里用git log -1 --pretty=%B取出最新提交的完整信息，再交给 gitru 校验。对于只做 squash merge 的团队，甚至可以在 Pull Request 的标题上下功夫，让 PR 合并生成的 commit message 自动带上规范的标题。

不过要提醒一点：CI 里的校验只能把关，不能纠正。如果提交信息不合规，CI 会挂红，开发者需要修改提交信息后再推一次。这通常是通过git commit --amend修改最新提交，或者用git rebase -i整理历史提交信息。团队初期偶尔出现这种返工很正常，磨合期过了就好了。

5. 实战排查：gitru 落地过程中的常见问题

5.1 Hook 不生效，先查这三处

我见过最多的问题，就是开发者配置完 hook 之后发现提交信息照样乱写，提交仍然成功。遇到这种情况，按顺序排查这三个点基本能定位问题。

第一是 hooksPath 有没有生效。执行git config core.hooksPath，看输出是不是你配置的路径。如果输出为空，说明 Git 还在用默认的.git/hooks目录。第二是 hook 文件有没有执行权限。在 Linux/macOS 上，ls -l .githooks/commit-msg看看有没有x权限位，没有就chmod +x。第三是脚本内容本身有没有问题。直接手动执行.githooks/commit-msg <某个包含提交信息的临时文件>，看看脚本能不能正确运行。

还有一个常见误区：有人把 hook 文件放在.git/hooks/commit-msg.sample，比如commit-msg.sample，Git 不会执行带.sample后缀的文件，必须重命名成commit-msg去掉后缀。这个坑我在刚接触 Git hooks 时也踩过，现在每次提到 hooks 都会下意识多说一句。

5.2 校验信息看不懂怎么办

gitru 的校验失败信息会明确告诉你哪条规则没通过，但很多刚接触规则式提交的同事还是会懵。我整理一个常见情况的对照表，方便排查：

这些错误信息的价值在于它们把“写清楚提交信息”这件事从玄学变成了可操作的规则。提交的人不需要“感觉”自己的提交信息写得好不好，规则会直接告诉他哪里不行、怎么改。

5.3 团队推广提交规范的现实策略

最后聊一个技术之外、但直接决定工具能不能落地的问题：怎么让团队接受提交规范。

我这几年给团队推过不少规范，总结下来的经验是：先立规则，再给工具，最后配兜底。立规则不是把一整套规范文档甩出来，而是先定一个最小集——类型走feat/fix/docs/chore起步，subject 长度控制在 72 字符以内，禁止update这类模糊词汇。这套规则任何人 5 分钟就能读懂，不会让人觉得“写了一辈子 commit，现在倒不会写了”。

配工具的过程要留意反馈。gitru 这种校验工具最怕的是“一刀切”的强约束，如果规则太严，比如强制 scope、强制每一个标点符号都符合规范，开发者会直接崩溃，然后疯狂用--no-verify绕过。我通常会在推行的第一周把所有--no-verify的用法收集起来看原因，凡是让人不舒服的规则就立刻调整。

兜底的意思是 CI 上的校验不能少，但心态要放平。本地 hook 是“提示”，CI 校验是“底线”。只要 CI 能拦住最核心的几条规则，其他一些非强制性的建议就让它过去，给人留出适应的空间。

实操心得：推行过程中最有效的一招是，把规范的示例直接放进仓库的CONTRIBUTING.md里，并且挂一个commit.template。Git 支持在提交时自动加载一个模板文件，开发者跑git commit时编辑器里会直接出现规范的格式，照着填空就行。这个模板配好之后，比任何培训都管用。

从脚本迁移到 gitru，我的几点真实体会

最后分享一些我个人的感受，也算是对这篇文章的一个收尾。

我之前在团队里用过 shell 脚本做提交校验，后来也试过 commitlint。shell 脚本的问题在于规则一多就掌控不住，尤其是转义和跨平台兼容性，每次换人维护都是一场灾难。commitlint 功能确实强，但为了一个校验工具引入整套 Node 工具链，总有一种杀鸡用牛刀、顺便把鸡窝也拆了的错觉。gitru 的出现刚好填补了我最需要的那一块：零依赖、单二进制、跨平台、规则可配置，安装和分发成本几乎可以忽略不计。

我印象最深的一次实践，是在一个没有 Node 环境的嵌入式团队里落地提交规范。以前我根本不敢想推 commitlint 这种方案，光跟每个人解释为什么要装 Node 就得花上半天。但换成 gitru 之后，直接把二进制文件发给团队，每个人把它放进 PATH 就算装好了。配置文件和 hooks 脚本随仓库走，大家 clone 下来配一次core.hooksPath就完事。两天之内团队的提交记录就肉眼可见地变得整齐了很多，那种“打开 git log 每一条都读得懂”的感觉，是真的舒服。

如果你也想试试，不用追求一步到位。先装好 gitru，配一份最简规则，从你自己开始用起。等你在 code review 里尝到了提交信息清晰的甜头，你自然会想把这份规范推广给整个团队。工具是死的人是活的，让工具为规范服务，比为工具迁就流程要靠谱得多。