Git钩子脚本如何检查周报内容

wen 实用脚本 2026-07-14 1

Git钩子脚本如何自动化检查周报内容

目录导读

为什么需要自动化检查周报？
Git钩子脚本基础概念
编写周报检查钩子：从零到实战
核心检查逻辑：模板、关键词与正则
常见问题与解决方案(Q&A)
进阶技巧：多钩子协同与团队规范

为什么需要自动化检查周报？

在软件研发团队中,周报是沟通进度、同步风险的重要载体，许多团队面临一个共同痛点：质量参差不齐——有人忘记填写关键任务，有人用“完成工作”这类模糊表述，甚至有人漏报阻塞项，传统的人工检查效率低下且容易遗漏。

Git钩子脚本如何检查周报内容

Git钩子脚本便成为理想的自动化工具，通过在pre-commit或pre-push阶段植入检查逻辑，团队可以强制要求每份周报满足最低质量标准，从而：

提升信息一致性：确保周报包含预期字段（如任务、进度、风险）。
减少审核负担：自动拦截不达标内容，降低人工挑错成本。
培养良好习惯：开发者每次提交都会自我校验，形成良性循环。

Git钩子脚本基础概念

Git钩子是Git仓库内的事件触发器,可在特定动作（如提交、推送）前后执行自定义脚本，常见钩子类型包括：

钩子名称	触发时机	适用场景
`pre-commit`	执行`git commit`前	检查代码格式、周报模板完整性
`commit-msg`	提交信息写入后	校验提交信息的格式
`pre-push`	执行`git push`前	运行测试、检查周报内容

工作流程示例：当开发者运行git commit时，系统自动调用.git/hooks/pre-commit脚本，解析周报文件（如weekly-report.md不符合规则（如缺少“下周计划”字段），则终止提交并给出错误提示。

编写周报检查钩子：从零到实战

步骤1：确定周报文件路径与格式

假设团队约定周报文件位于项目根目录的/reports文件夹下，文件名格式为YYYY-MM-DD-姓名.md模板如下：

# 周报（YYYY-MM-DD - YYYY-MM-DD）
## 本周完成
- [x] 任务A：完成数据库优化（耗时6h）
- [ ] 任务B：对接API文档（未完成，原因：等待上游接口）
## 下周计划
- 任务C：开始前端重构
- 任务D：同步测试环境部署
## 风险与阻塞
- 风险1：第三方依赖库版本冲突

步骤2：编写`pre-commit`钩子脚本（可选使用Python或Shell）

以下为Python版本的示例脚本（保存至.git/hooks/pre-commit）：

#!/usr/bin/env python3
import re, sys, os, glob
REPORT_DIR = "reports"
REQUIRED_SECTIONS = ["本周完成", "下周计划", "风险与阻塞"]
DATE_PATTERN = r"^\d{4}-\d{2}-\d{2}$"
def check_report(file_path):
    with open(file_path, 'r') as f:
        content = f.read()
    # 1. 检查是否包含所有必需小节
    for section in REQUIRED_SECTIONS:
        if section not in content:
            print(f"错误：{file_path} 缺少【{section}】小节")
            return False
    # 2. 检查【本周完成】下是否有具体任务（至少一行非空且包含“-”或“*”）
    task_pattern = re.compile(r"##\s*本周完成\s*\n(.*?)(?=\n##\s|$)", re.DOTALL)
    match = task_pattern.search(content)
    if not match or not re.search(r"^\s*[-*]\s.*$", match.group(1), re.MULTILINE):
        print(f"错误：{file_path} 的【本周完成】小节没有具体任务条目")
        return False
    # 3. 检查是否提及“阻塞”或“风险”等关键词
    risk_keywords = ["阻塞", "风险", "无法推进", "依赖", "等待"]
    if not any(kw in content for kw in risk_keywords):
        # 允许明确标注“无风险”的情况
        if "无风险" not in content and "无阻塞" not in content:
            print(f"警告：{file_path} 未提及任何风险或阻塞项，请确认后忽略或补充")
            # 这里可以设计为仅警告，不阻断（通过return True，但打印提示）
    return True
# 遍历所有周报文件
all_reports = glob.glob(f"{REPORT_DIR}/*.md")
errors = []
for report in all_reports:
    if not check_report(report):
        errors.append(report)
if errors:
    print("\n周报检查未通过，请修正后重新提交：")
    for e in errors:
        print(f"  - {e}")
    sys.exit(1)
else:
    print("周报检查通过！")
    sys.exit(0)

步骤3：赋予执行权限并测试

chmod +x .git/hooks/pre-commit

尝试提交一个缺失“下周计划”的周报，提交会被拒绝并显示错误信息。

核心检查逻辑：模板、关键词与正则

为满足不同团队需求,检查脚本可支持以下扩展规则：

规则类型	实现方式	示例
必填字段	直接字符串匹配	`"下周计划" in content`
任务格式	正则表达式匹配列表符号	`r"^\s[-]\s.*$"`
时间完整性	正则匹配日期格式	`r"\d{4}-\d{2}-\d{2}"`
风险检测	关键词黑名单/白名单	检测“阻塞”“依赖”等词

重要提示：正则表达式在不同语言中略有差异，建议在本地先测试一轮（如用Python的re模块）。

常见问题与解决方案(Q&A)

Q1：团队使用不同语言写的周报，脚本能处理吗？
A：可以，脚本只需基于文本匹配（如关键词列表支持中英文），或者解析Markdown结构（如用re.DOTALL匹配多段内容），也可以为每类语言单独配置检查文件。

Q2：如果某个开发者需要临时跳过检查（如测试提交）怎么办？
A：引入环境变量SKIP_WEEKLY_CHECK，当检测到该变量时，跳过检查，在pre-commit脚本开头添加：

import os
if os.environ.get('SKIP_WEEKLY_CHECK'):
    print("警告：周报检查已跳过（由环境变量控制）")
    sys.exit(0)

使用时：SKIP_WEEKLY_CHECK=1 git commit -m "测试"，注意配合团队纪律使用。

Q3：周报文件不在根目录，且有多级文件夹怎么办？
A：使用os.walk递归遍历REPORT_DIR下的所有.md文件，这样能覆盖嵌套目录。

Q4：是否可以在推送（pre-push）时检查，而不是提交时？
A：完全可以，将上述逻辑复制到.git/hooks/pre-push脚本即可，区别在于pre-push在远程推送前执行，会多一道防线，但检查失败时无法直接修改提交历史。

进阶技巧：多钩子协同与团队规范

与代码检查钩子并存：确保pre-commit钩子中同时包含代码格式校验（如eslint）和周报检查，使用&&或类似逻辑串联。
团队级钩子分发：将钩子脚本纳入项目仓库的.githooks目录，并在README中说明如何启用（通过git config core.hooksPath .githooks）。
动态阈值调整：在脚本中读取外部规则文件（如weekly-check-config.json），方便非开发人员调整关键词、必填项等。
出错时提供修复提示：除了指出文件名称和缺失小节，还可给出修复示例，降低开发者额学习成本。