Git钩子脚本如何检查文档完整性

本文目录导读：

1. 结构完整性检查（JSON/YAML/Markdown）
2. Markdown链接检查
3. 文档模板完整性检查
4. 文档版本一致性检查
5. XML/SGML格式检查
6. 完整的pre-commit钩子示例
7. 安装建议

Git钩子脚本可以通过多种方式检查文档完整性,以下是几种常见的方法：

结构完整性检查（JSON/YAML/Markdown）

JSON文件检查

#!/bin/bash
# .git/hooks/pre-commit
# 检查所有修改的JSON文件
for file in $(git diff --cached --name-only --diff-filter=ACM | grep '\.json$'); do
    if [ -f "$file" ]; then
        python3 -c "import json; json.load(open('$file'))" 2>/dev/null
        if [ $? -ne 0 ]; then
            echo "❌ 无效的JSON文件: $file"
            exit 1
        fi
    fi
done

YAML文件检查

# 需要安装 yamllint
for file in $(git diff --cached --name-only --diff-filter=ACM | grep -E '\.(yaml|yml)$'); do
    if [ -f "$file" ]; then
        yamllint "$file" > /dev/null 2>&1
        if [ $? -ne 0 ]; then
            echo "❌ YAML语法错误: $file"
            exit 1
        fi
    fi
done

Markdown链接检查

# 使用markdown-link-check工具
for file in $(git diff --cached --name-only --diff-filter=ACM | grep '\.md$'); do
    if [ -f "$file" ]; then
        markdown-link-check "$file" --quiet
        if [ $? -ne 0 ]; then
            echo "❌ Markdown中存在失效链接: $file"
            exit 1
        fi
    fi
done

文档模板完整性检查

#!/bin/bash
# 检查文档是否包含必需的部分
REQUIRED_SECTIONS=(
    "## 概述"
    "## 使用方法"
    "## 参数说明"
)
for file in $(git diff --cached --name-only --diff-filter=ACM | grep -E '\.(md|txt)$'); do
    if [ -f "$file" ]; then
        for section in "${REQUIRED_SECTIONS[@]}"; do
            if ! grep -q "$section" "$file"; then
                echo "❌ $file 缺少 $section 部分"
                exit 1
            fi
        done
    fi
done

文档版本一致性检查

#!/bin/bash
# 检查文档中的版本号是否与代码版本一致
VERSION_FILE="VERSION"
DOC_FILES=$(git diff --cached --name-only --diff-filter=ACM | grep -E '\.(md|rst|txt)$')
if [ -f "$VERSION_FILE" ]; then
    VERSION=$(cat "$VERSION_FILE")
    for file in $DOC_FILES; do
        # 检查文档中是否包含正确的版本号
        if grep -q "version" "$file" 2>/dev/null; then
            if ! grep -q "$VERSION" "$file"; then
                echo "⚠️  警告: $file 可能包含过时版本号"
                # 或者 exit 1 如果严格要求版本一致
            fi
        fi
    done
fi

XML/SGML格式检查

#!/bin/bash
# 检查XML文档格式
for file in $(git diff --cached --name-only --diff-filter=ACM | grep -E '\.(xml|sgml)$'); do
    if [ -f "$file" ]; then
        # 使用xmllint检查
        xmllint --noout "$file" 2>/dev/null
        if [ $? -ne 0 ]; then
            echo "❌ 无效的XML格式: $file"
            exit 1
        fi
    fi
done

完整的pre-commit钩子示例

创建 .git/hooks/pre-commit 文件：

#!/bin/bash
echo "🔍 开始文档完整性检查..."
FAILED=0
# 1. 检查语法格式
check_syntax() {
    local ext=$1
    local files=$(git diff --cached --name-only --diff-filter=ACM | grep "\\.$ext$")
    for file in $files; do
        case $ext in
            json)
                python3 -m json.tool "$file" > /dev/null 2>&1 || return 1
                ;;
            yaml|yml)
                python3 -c "import yaml; yaml.safe_load(open('$file'))" > /dev/null 2>&1 || return 1
                ;;
            xml)
                xmllint --noout "$file" > /dev/null 2>&1 || return 1
                ;;
        esac
    done
    return 0
}
# 2. 检查Markdown质量
check_markdown() {
    local files=$(git diff --cached --name-only --diff-filter=ACM | grep "\\.md$")
    for file in $files; do
        # 检查空标题
        if grep -q "^#\+ $" "$file"; then
            echo "❌ $file 包含空标题"
            return 1
        fi
        # 检查连续空行超过2行
        if grep -q "^$" "$file" | uniq | wc -l | awk '{if($1>2) exit 1}'; then
            echo "⚠️  $file 包含过多空行"
        fi
    done
    return 0
}
# 3. 检查文档长度
check_length() {
    local max_lines=500
    local files=$(git diff --cached --name-only --diff-filter=ACM | grep -E '\.(md|txt)$')
    for file in $files; do
        local lines=$(wc -l < "$file")
        if [ "$lines" -gt "$max_lines" ]; then
            echo "⚠️  警告: $file 文档过长 ($lines 行)"
        fi
    done
}
# 执行检查
check_syntax "json" || FAILED=1
check_syntax "yaml" || FAILED=1
check_syntax "xml" || FAILED=1
check_markdown || FAILED=1
check_length
# 结果
if [ $FAILED -eq 1 ]; then
    echo "❌ 文档完整性检查失败"
    exit 1
else
    echo "✅ 文档完整性检查通过"
fi

安装建议

# 确保钩子脚本可执行
chmod +x .git/hooks/pre-commit
# 或者使用 Git 模板自动复制
git config --global init.templatedir '~/.git-templates'
mkdir -p ~/.git-templates/hooks
cp pre-commit ~/.git-templates/hooks/

这些钩子脚本可以根据项目需求组合使用，建议从基础语法检查开始,逐步增加更复杂的完整性和一致性检查。