git-hooks

Git Hooks 技能

何时启用

在以下情况下启用此技能：

• 设置提交前钩子
• 配置提交消息验证
• 安装密钥扫描器
• 强制执行代码质量标准
• 自动运行推送前测试

快速安装

# Use interactive installer (recommended)
./AgentUsage/pre_commit_hooks/install_hooks.sh

# Or manual installation for Python project
cp AgentUsage/pre_commit_hooks/commit-msg .git/hooks/
cp AgentUsage/pre_commit_hooks/pre-commit-python .git/hooks/pre-commit
cp AgentUsage/pre_commit_hooks/pre-commit-secrets-scanner .git/hooks/pre-commit-secrets
cp AgentUsage/pre_commit_hooks/pre-push .git/hooks/
chmod +x .git/hooks/*

可用钩子

核心钩子（所有项目）

钩子	用途
commit-msg	验证 Conventional Commits 格式
pre-commit-secrets-scanner	防止 API 密钥/密钥泄露

特定语言钩子

钩子	语言	检查项
pre-commit-python	Python	Black、Ruff
pre-commit-javascript	JS/TS	Prettier、ESLint、TypeScript
pre-commit-go	Go	gofmt、go vet
pre-commit-multi-language	混合语言	自动检测并运行相应工具

自动化钩子

钩子	用途
pre-push	推送前运行测试
post-checkout	切换分支时自动更新依赖项
post-commit	显示提交摘要和 TODO

按项目选择钩子

# Python Project
commit-msg + pre-commit-python + pre-commit-secrets-scanner + pre-push

# JavaScript Project
commit-msg + pre-commit-javascript + pre-commit-secrets-scanner + pre-push

# Go Project
commit-msg + pre-commit-go + pre-commit-secrets-scanner + pre-push

# Multi-language
commit-msg + pre-commit-multi-language + pre-commit-secrets-scanner + pre-push

各钩子的作用

commit-msg

验证提交消息格式：

# Accepted formats
feat: Add user authentication
fix: Correct validation error
docs(readme): Update installation

# Rejected
Update files  # No type
feat add feature  # Missing colon

pre-commit-secrets-scanner

扫描是否存在泄露的密钥：

• Anthropic API 密钥（sk-ant-...）
• OpenAI API 密钥（sk-...）
• AWS 凭据（AKIA...）
• GitHub 令牌（ghp_...）
• 硬编码密码

pre-commit-python

# Runs automatically on staged .py files
uv run black --check $file
uv run ruff check $file

pre-push

# Runs before push
uv run pytest tests/  # or pnpm test, go test, cargo test

测试钩子

# Test pre-commit directly
.git/hooks/pre-commit

# Test with sample commit
git add .
git commit -m "test: verify hooks"

# Run with debug output
bash -x .git/hooks/pre-commit

绕过钩子（仅限紧急情况）

# Skip all hooks
git commit --no-verify -m "Emergency fix"

# Only use when:
# - Emergency production fixes
# - Hook malfunction
# - Intentional override

故障排除

钩子未运行

# Check existence
ls -l .git/hooks/

# Fix permissions
chmod +x .git/hooks/*

# Check syntax
bash -n .git/hooks/pre-commit

权限被拒绝

chmod +x .git/hooks/*

质量检查未通过

# Run tools manually
uv run black --check .
uv run ruff check .

# Fix issues
uv run black .
uv run ruff check --fix .

# Retry commit
git commit -m "Your message"

缺少工具

# Install code quality tools
uv add --dev black ruff

# Verify installation
which black
uv run black --version

自定义钩子配置

为你的项目修改 pre-commit

#!/bin/bash
# .git/hooks/pre-commit

# Get staged Python files
FILES=$(git diff --cached --name-only --diff-filter=ACM | grep '\.py$')

if [ -n "$FILES" ]; then
    # Run your tools
    uv run black --check $FILES || exit 1
    uv run ruff check $FILES || exit 1
fi

exit 0

钩子执行顺序

1. pre-commit - 提交前（代码质量）
2. commit-msg - 验证消息格式
3. post-commit - 提交后（通知）
4. pre-push - 推送前（测试）

最佳实践

应当 ✅

• 在所有项目中安装密钥扫描器
• 使用 commit-msg 保持历史记录一致
• 在 pre-push 中运行测试
• 安装后测试钩子

不应 ❌

• 经常跳过钩子
• 禁用密钥扫描
• 忽略钩子运行失败
• 未先测试钩子就提交

相关资源

参见 AgentUsage/pre_commit_hooks/：

• setup_guide.md - 完整安装指南
• examples.md - 自定义钩子示例
• TROUBLESHOOTING.md - 常见问题
• 各个钩子脚本，供参考