Git 工作流强制执行器(Git Workflow Enforcer)
强制执行一致的 Git 工作流,包括提交消息、分支命名和 PR 流程。
何时使用
- 创建提交或分支时
- 进行代码审查或 PR 创建时
- 用户提及“git workflow”、“commit message”、“branch naming”或“pull request”时
指令
1. 检测现有约定
检查是否存在:
.github/或.gitlab/模板CONTRIBUTING.md- 现有提交消息模式
- 分支命名模式
2. 约定式提交(Conventional Commits)
格式: type(scope): description
类型:
feat: 新功能fix: 错误修复docs: 文档style: 格式整理、缺失分号refactor: 代码重构perf: 性能提升test: 添加测试chore: 维护、依赖项
示例:
feat(auth): add OAuth2 login support
fix(api): handle null response in user endpoint
docs(readme): update installation instructions
refactor(utils): simplify date formatting logic
3. 分支命名
常见模式:
feature/user-authentication
bugfix/login-error-handling
hotfix/critical-security-patch
release/v1.2.0
chore/update-dependencies
验证:
- 小写字母,使用连字符
- 以类型为前缀
- 描述性名称
- 如果适用,包含问题编号:
feature/123-add-dark-mode
4. 提交消息验证
好的提交:
feat(payments): integrate Stripe payment gateway
- Add Stripe SDK configuration
- Implement payment intent creation
- Add webhook handler for payment events
- Update tests for payment flow
Closes #456
检查以下内容:
- 标题行 ≤50 个字符
- 正文每行 72 个字符自动换行
- 标题和正文之间有一个空行
- 祈使语气(使用“add”而非“added”)
- 引用问题/工单
5. PR 模板
创建 .github/PULL_REQUEST_TEMPLATE.md:
## Description
<!-- What does this PR do? -->
## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update
## Testing
<!-- How was this tested? -->
## Checklist
- [ ] Code follows project style guidelines
- [ ] Self-review completed
- [ ] Comments added for complex code
- [ ] Documentation updated
- [ ] Tests added/updated
- [ ] All tests passing
- [ ] No new warnings
## Related Issues
Closes #
6. 提交挂钩(Commit Hooks)
预提交挂钩:
#!/bin/sh
# .git/hooks/pre-commit
# Run linter
npm run lint
# Run tests
npm test
# Check for sensitive data
if git diff --cached | grep -i "password\|api_key\|secret"; then
echo "Error: Possible sensitive data detected"
exit 1
fi
提交消息挂钩:
#!/bin/sh
# .git/hooks/commit-msg
commit_msg=$(cat "$1")
# Check conventional commit format
if ! echo "$commit_msg" | grep -qE "^(feat|fix|docs|style|refactor|perf|test|chore)(\(.+\))?: .+"; then
echo "Error: Commit message must follow Conventional Commits format"
echo "Example: feat(auth): add login feature"
exit 1
fi
7. 验证现有提交
检查最近的提交是否符合模式:
git log --oneline -20 | grep -v "^[a-f0-9]\{7\} (feat|fix|docs|style|refactor|perf|test|chore)"
8. 生成变更日志(Changelog)
从约定式提交生成:
# 使用 standard-version
npx standard-version
# 或按类型手动分组
git log --pretty=format:"%s" | grep "^feat" > features.txt
git log --pretty=format:"%s" | grep "^fix" > fixes.txt
9. 受保护分支
GitHub 设置:
- 要求 PR 审查
- 要求状态检查通过
- 要求签名提交
- 限制谁可以推送
- 要求线性历史
10. 最佳实践
- 原子提交:每次提交只包含一个逻辑更改
- 描述性消息:解释为什么,而不是做什么
- 频繁提交:小而频繁优于大而稀少
- 干净历史:合并前进行压缩(squash)或变基(rebase)
- 签名提交:使用 GPG 签名确保安全
- 引用问题:链接到追踪系统
Git 提交模板
创建 .gitmessage:
<type>(<scope>): <subject>
<body>
<footer>
# Type: feat, fix, docs, style, refactor, perf, test, chore
# Scope: component or file affected
# Subject: imperative, lowercase, no period, ≤50 chars
# Body: explain what and why, not how, wrapped at 72 chars
# Footer: breaking changes, issue references
设置为模板:
git config --global commit.template ~/.gitmessage
支持文件
templates/PULL_REQUEST_TEMPLATE.mdtemplates/commit-msg-hook.shtemplates/.gitmessage