Git钩子脚本如何检查知识沉淀

本文目录导读：

1. 技术文档钩子实现
2. 知识沉淀质量检查
3. 知识沉淀关联检查
4. 知识沉淀模板检查
5. 完整示例项目结构
6. 安装脚本
7. 最佳实践建议

我来详细介绍Git钩子脚本检查知识沉淀的方法和最佳实践。

技术文档钩子实现

pre-commit 钩子：检查文档完整性

#!/bin/bash
# .git/hooks/pre-commit
# 检查技术文档必须包含的章节
check_documentation_sections() {
    local files=$(git diff --cached --name-only --diff-filter=ACM | grep -E '\.(md|txt|rst)$')
    local has_error=false
    for file in $files; do
        # 获取文件内容
        local content=$(git show :$file)
        # 检查必需章节
        local required_sections=("背景" "方案" "quot; "注意事项")
        local missing_sections=()
        for section in "${required_sections[@]}"; do
            if ! echo "$content" | grep -qi "$section"; then
                missing_sections+=("$section")
            fi
        done
        if [ ${#missing_sections[@]} -gt 0 ]; then
            echo "❌ $file 缺少必需章节: ${missing_sections[*]}"
            has_error=true
        fi
        # 检查代码示例完整性
        if echo "$content" | grep -q '```' ; then
            local code_blocks=$(echo "$content" | grep -c '```')
            if [ $((code_blocks % 2)) -ne 0 ]; then
                echo "❌ $file 代码块未闭合"
                has_error=true
            fi
        fi
    done
    if $has_error; then
        exit 1
    fi
}
# 检查注释规范
check_comment_quality() {
    local files=$(git diff --cached --name-only --diff-filter=ACM | grep -E '\.(py|js|java|go)$')
    for file in $files; do
        # 检查是否包含TODO注释
        if git show :$file | grep -qi "TODO"; then
            echo "⚠️ $file 包含 TODO 注释，建议记录到 issue 系统"
        fi
        # 检查Python文件的docstring
        if [[ $file == *.py ]]; then
            local functions=$(grep -c "def " <<< "$(git show :$file)")
            local docstrings=$(grep -c '"""' <<< "$(git show :$file)")
            if [ "$functions" -gt 0 ] && [ "$docstrings" -eq 0 ]; then
                echo "⚠️ $file 包含函数但没有文档字符串"
            fi
        fi
    done
}
# 检查提交信息质量
check_commit_message() {
    local msg_file=$1
    # 检查关键字要求
    local required_keywords=("问题" "解决" "影响范围")
    local missing_keywords=()
    for keyword in "${required_keywords[@]}"; do
        if ! grep -qi "$keyword" "$msg_file"; then
            missing_keywords+=("$keyword")
        fi
    done
    if [ ${#missing_keywords[@]} -gt 0 ]; then
        echo "❌ 提交信息缺少: ${missing_keywords[*]}"
        echo "建议格式: [类型] 简要描述 (问题:xxx, 解决:xxx, 影响:xxx)"
        exit 1
    fi
}
# 主流程
case "$1" in
    "")
        check_documentation_sections
        check_comment_quality
        ;;
    "commit-msg")
        check_commit_message "$2"
        ;;
esac

知识沉淀质量检查

commit-msg 钩子：确保提交信息包含决策记录

#!/bin/bash
# .git/hooks/commit-msg
validate_knowledge_record() {
    local commit_msg=$(cat "$1")
    # 检查是否包含决策记录标记
    if echo "$commit_msg" | grep -qiE '(ADR|决策记录|技术选型|方案对比)'; then
        # 检查结构化信息
        local required_fields=("日期" "决策者" "选项" "quot; "理由")
        local missing_fields=()
        for field in "${required_fields[@]}"; do
            if ! echo "$commit_msg" | grep -qi "$field"; then
                missing_fields+=("$field")
            fi
        done
        if [ ${#missing_fields[@]} -gt 0 ]; then
            echo "❌ 决策记录格式不完整，缺少: ${missing_fields[*]}"
            echo "建议格式："
            echo "日期: $(date +%Y-%m-%d)"
            echo "决策者: "
            echo "选项: "
            echo " "
            echo "理由: "
            exit 1
        fi
    fi
    # 检查代码变更描述
    if echo "$commit_msg" | grep -qiE '(fix|修复|bug|bugfix)'; then
        if ! echo "$commit_msg" | grep -qiE '(根因|root.cause|分析|analysis)'; then
            echo "⚠️ Bug修复建议包含根因分析"
        fi
    fi
    # 检查新增功能描述
    if echo "$commit_msg" | grep -qiE '(feat|feature|新增|add)'; then
        if ! echo "$commit_msg" | grep -qiE '(设计|设计思路|architecture|用途)'; then
            echo "⚠️ 新功能建议包含设计说明"
        fi
    fi
}
validate_knowledge_record "$1"

知识沉淀关联检查

pre-push 钩子：关联知识库

#!/bin/bash
# .git/hooks/pre-push
check_knowledge_base_link() {
    local branch=$(git symbolic-ref HEAD 2>/dev/null | sed 's/refs\/heads\///')
    # 检查是否关联了知识库
    local knowledge_base="docs/knowledge-base"
    if [ -d "$knowledge_base" ]; then
        # 检查是否创建了对应的知识记录
        local has_record=false
        local record_pattern=""
        case "$branch" in
            feature/*|feat/*)
                record_pattern="docs/knowledge-base/features/${branch#*/}.md"
                ;;
            fix/*|bugfix/*)
                record_pattern="docs/knowledge-base/bug-fixes/${branch#*/}.md"
                ;;
            refactor/*)
                record_pattern="docs/knowledge-base/decisions/${branch#*/}.md"
                ;;
        esac
        if [ -n "$record_pattern" ] && [ ! -f "$record_pattern" ]; then
            echo "⚠️ 分支 '$branch' 没有对应的知识记录"
            echo "建议创建: $record_pattern"
            echo "你可以继续推送，但建议补充知识沉淀"
        fi
    fi
}
check_knowledge_base_link

知识沉淀模板检查

定义模板文件 (docs/knowledge-templates/)

技术决策模板:

# 技术决策记录 - {标题}
## 基本信息
- 日期: {YYYY-MM-DD}
- 决策者: {姓名}
- 关联Issue: #{issue_id}
## 背景
{问题和上下文描述}
## 选项分析
| 选项 | 优点 | 缺点 | 评估 |
|------|------|------|------|
| A   |      |      |      |
| B   |      |      |      |
## 
{选择的方案和理由}
## 影响范围
{列出受影响的模块和团队}

完整示例项目结构

# 项目钩子配置
project/
├── .git/
│   └── hooks/
│       ├── pre-commit          # 文档和注释检查
│       ├── commit-msg          # 知识记录检查
│       ├── pre-push            # 知识库关联检查
│       └── prepare-commit-msg  # 自动注入模板
├── docs/
│   ├── knowledge-base/         # 知识库目录
│   │   ├── features/
│   │   ├── decisions/
│   │   └── bug-fixes/
│   └── knowledge-templates/    # 模板目录
│       ├── decision.md
│       ├── bug-fix.md
│       └── feature.md
└── scripts/
    └── install-hooks.sh        # 安装脚本

安装脚本

#!/bin/bash
# scripts/install-hooks.sh
HOOKS_DIR=".git/hooks"
# 安装钩子
install_hook() {
    local hook_name=$1
    local hook_path="${HOOKS_DIR}/${hook_name}"
    # 备份已有钩子
    if [ -f "$hook_path" ] && [ ! -L "$hook_path" ]; then
        mv "$hook_path" "${hook_path}.backup"
    fi
    # 创建软链接
    ln -sf "../../scripts/git-hooks/${hook_name}" "$hook_path"
    chmod +x "$hook_path"
    echo "✅ Installed ${hook_name} hook"
}
# 创建钩子目录
mkdir -p scripts/git-hooks
# 安装所有钩子
for hook in pre-commit commit-msg pre-push prepare-commit-msg; do
    install_hook "$hook"
done
# 复制模板
cp -r docs/knowledge-templates docs/knowledge-base/
echo "✅ All hooks installed successfully"

最佳实践建议

1. 渐进式检查：开始时不强制检查，只给出建议，等团队适应再加强
2. 跳过机制：允许在紧急情况下跳过检查

   git commit --no-verify  # 跳过钩子

3. 提供修复建议：检查失败时应给出明确的修复指导
4. 团队培训：配合文档，确保团队理解钩子规则
5. 持续改进：定期review钩子规则，根据团队反馈调整

通过以上Git钩子脚本,可以有效促进团队的知识沉淀习惯，提高代码和文档质量。