Git钩子脚本如何检查提交信息格式

wen 实用脚本 2026-07-15 1

掌握Git钩子脚本：如何自动检查提交信息格式，提升团队协作效率

目录导读

为什么需要检查提交信息格式
Git钩子脚本基础
编写commit-msg钩子检查格式
实战：正则表达式匹配规范
常见问题与问答
提升技巧：团队级钩子分发

为什么需要检查提交信息格式

在团队开发中,git commit 信息往往是代码历史的“说明书”。混乱的提交信息（如“fix bug”、“update”）会让后期回溯、版本发布、自动生成CHANGELOG变得极其困难。
通过 Git钩子脚本 在提交前自动校验格式，可以强制团队遵循统一规范（如：Conventional Commits 或自定义 <type>(<scope>): <description>）。
核心价值：

Git钩子脚本如何检查提交信息格式

自动化审计,减少人工Code Review负担
生成清晰的版本历史,支持自动化版本号提升
提升CI/CD流程中解析提交信息的准确率

Git钩子脚本基础

Git钩子（Hook）是位于 .git/hooks/ 目录下的可执行脚本，关键生命周期钩子包括：

pre-commit：提交前检查文件
commit-msg：专门检查提交信息（本文核心）
pre-push：推送前检查

脚本语言不限：Shell、Python、Node.js、Ruby均可用，对于跨平台团队，推荐使用 Python 或 Node.js，避免Shell差异。

编写commit-msg钩子检查格式

1 创建钩子文件

在项目根目录创建 .git/hooks/commit-msg（注意无扩展名），并赋予执行权限：

chmod +x .git/hooks/commit-msg

2 基础Shell脚本示例

#!/bin/sh
commit_msg_file=$1
commit_msg=$(cat "$commit_msg_file")
# 检查是否符合格式：<type>(<scope>): <description>
if ! echo "$commit_msg" | grep -qE '^(feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert)\([a-z]+\): .{1,50}$'; then
    echo "❌ 错误：提交信息格式不符合规范！"
    echo "格式要求：<type>(<scope>): <description>"
    echo "示例：feat(user): add login validation"
    exit 1
fi

注意：脚本必须用 exit 1 终止提交，否则允许通过。

实战：正则表达式匹配规范

1 常见规范模式

规范类型	正则示例	说明
Conventional Commits	`^(feat\|fix\|docs)!?: .+`	支持表示破坏性变更
自定义多范围	`^(feat\|fix)$[a-z0-9-]+$: .{1,50}$`	限制作用域为字母数字和连字符
禁止空信息	最少非空字符

2 高级Python脚本（推荐跨平台）

#!/usr/bin/env python3
import sys, re
commit_msg_file = sys.argv[1]
with open(commit_msg_file, 'r') as f:
    first_line = f.readline().strip()
pattern = r'^(feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert)\([a-z0-9-]+\): .{1,100}$'
if not re.match(pattern, first_line):
    print("❌ 提交信息不符合规范！")
    print("正确格式：type(scope): description")
    print("feat(auth): implement OAuth2.0")
    sys.exit(1)
else:
    print("✅ 提交信息格式通过检测")

常见问题与问答

Q1: 如何绕过钩子提交？

A: 使用 git commit --no-verify 可临时跳过钩子，但不建议滥用，团队应通过CI强制执行，并记录跳过的提交。

Q2: 钩子脚本能否检查多行提交信息？

A: 可以，脚本默认读取整个提交信息（包括body和footer），若只需检查第一行，可重点处理 first_line。

Q3: 钩子脚本为什么没有生效？

A: 检查两点：

文件名必须是 commit-msg（无后缀）
必须位于 .git/hooks/ 目录，且赋予 chmod +x
脚本首行 #!/bin/sh 或 #!/usr/bin/env python3 必须正确

Q4: 团队如何分发钩子？

A: 使用 [husky]（https://typicode.github.io/husky/）或 [pre-commit]（https://pre-commit.com）管理钩子，将配置文件 pre-commit-config.yaml 或 .husky/ 目录纳入Git版本控制。

提升技巧：团队级钩子分发

husky（Node.js项目）
1. 安装 npm install --save-dev husky
2. 在 package.json 中配置：
```
"husky": {
"hooks": {
 "commit-msg": "npx --no-install commitlint --edit $1"
}
}
```
  结合 [commitlint]（https://commitlint.js.org）实现零配置规范检查。
pre-commit框架（多语言项目）
在项目根目录创建 .pre-commit-config.yaml：
```
- repo: https://github.com/alessandrojcm/commitlint-pre-commit-hook
  rev: v9.1.1
  hooks:
    - id: commitlint
```
然后运行 pre-commit install 自动安装钩子。

CI强制回退
在GitHub Actions中增加步骤检查提交信息，若不符合则自动标记 invalid 标签：

- name: Check commit message
  run: |
    if ! echo "${{ github.event.head_commit.message }}" | grep -qP 'pattern'; then
      exit 1
    fi

Git钩子脚本是确保提交信息规范的“守门员”，通过本文的示例，你可以快速实现从Shell到Python的钩子，并利用husky或pre-commit工具实现团队级自动化，若你的项目需要更复杂的校验（如Jira编号、链接检测），只需修改正则表达式即可。
最终推荐：将钩子脚本与CI/CD结合，实现从本地到远程的全面合规拦截，提升代码库的长期可维护性。