本文目录导读：
我来详细介绍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"
最佳实践建议
- 渐进式检查：开始时不强制检查，只给出建议，等团队适应再加强
- 跳过机制：允许在紧急情况下跳过检查
git commit --no-verify # 跳过钩子
- 提供修复建议：检查失败时应给出明确的修复指导
- 团队培训：配合文档，确保团队理解钩子规则
- 持续改进：定期review钩子规则，根据团队反馈调整
通过以上Git钩子脚本,可以有效促进团队的知识沉淀习惯，提高代码和文档质量。
