| name | git-workflow |
| description | Git 工作流专家。规范化版本控制，确保提交历史清晰可追溯。支持 Conventional Commits 规范、Pull Request 最佳实践、分支管理策略和自动化工作流。 |
| metadata | {"short-description":"Git 工作流与版本控制","keywords":["git-workflow","Git","版本控制","Conventional Commits","Pull Request","分支管理","提交规范"],"category":"版本控制","author":"Bensz Conan","platform":"Claude Code | OpenAI Codex | ChatGPT"} |
Git Workflow - Git 工作流专家
BenszAPI 任务工作区
本 Skill 的新任务中间文件统一写入 ./.bensz-api/task-{yyyymmdd-hhmm}-{简短描述}/{skill名}/input|output|log/。同一任务复用一个任务根目录；多 Skill 协作才创建 shared/。正式交付物不写入该目录，历史隐藏目录只允许显式兼容读取、迁移或清理。
与 bensz-collect-bugs 的协作约定
- 因本 skill 设计缺陷导致的 bug，先用
bensz-collect-bugs 规范记录到 ~/.bensz-skills/bugs/，不要直接修改用户本地已安装的 skill 源码；若有 workaround，先记 bug，再继续完成任务。
- 只有用户明确要求“report bensz skills bugs”等公开上报时，才用本地
gh 上传新增 bug 到 huangwb8/bensz-bugs；不要 pull / clone 整个仓库。
核心理念
良好的 Git 实践 是团队协作的基础：
┌─────────────────────────────────────────────────────────┐
│ 规范提交 → 清晰历史 → 易于回溯 → 高效协作 │
└─────────────────────────────────────────────────────────┘
核心原则：
- ✅ 提交历史即文档
- ✅ 原子提交，单一职责
- ✅ 清晰的可追溯性
- ✅ 易于 Code Review
何时使用本技能
在以下场景时激活：
- 需要 Git 提交（commit）
- 创建 Pull Request / Merge Request
- 代码分支管理
- 版本发布
- 提到"git"、"提交"、"分支"、"PR"
Conventional Commits 规范
提交格式
<type>(<scope>): <subject>
<body>
<footer>
Type 类型
| Type | 说明 | 示例 |
|---|
feat | 新功能 | feat(auth): add OAuth2 login |
fix | Bug 修复 | fix(api): resolve timeout issue |
docs | 文档变更 | docs(readme): update installation |
style | 代码格式 | style(lint): fix indentation |
refactor | 重构 | refactor(utils): extract validator |
perf | 性能优化 | perf(db): add query index |
test | 测试相关 | test(user): add login tests |
chore | 构建/工具 | chore(deps): upgrade to v2.0 |
revert | 回滚提交 | revert: feat(auth) |
提交示例
feat(auth): add JWT token validation
feat(payment): integrate Stripe payment gateway
Implement credit card payment processing using Stripe API.
Add webhook handling for payment status updates.
- Add Stripe client initialization
- Implement payment intent creation
- Add webhook endpoint for status updates
- Handle payment success/failure scenarios
Closes
Related
提交最佳实践
1. 原子提交原则
git commit -m "feat: add user feature and fix bugs and update docs"
git commit -m "feat(user): add registration"
git commit -m "fix(auth): resolve session timeout"
git commit -m "docs(readme): update examples"
2. 提交大小控制
| 类型 | 行数变化 | 建议 |
|---|
| 小型 | < 100 行 | ✅ 理想 |
| 中型 | 100-400 行 | ⚠️ 可接受 |
| 大型 | > 400 行 | ❌ 应拆分 |
3. 提交信息质量
git commit -m "update"
git commit -m "fix bug"
git commit -m "wip"
git commit -m "fix(auth): resolve JWT validation error"
git commit -m "feat(api): add rate limiting middleware"
git commit -m "docs(guide): explain authentication flow"
分支管理策略
分支命名规范
| 类型 | 格式 | 示例 |
|---|
| 功能 | feature/* | feature/user-auth |
| 修复 | bugfix/* | bugfix/login-timeout |
| 热修复 | hotfix/* | hotfix/security-patch |
| 发布 | release/* | release/v1.2.0 |
| 实验 | experiment/* | experiment/new-ui |
分支工作流
main (生产)
↑
├── release/v1.2.0 (发布准备)
│ ↑
│ ├── feature/user-auth (功能开发)
│ ├── feature/payment-api (功能开发)
│ └── bugfix/login-issue (Bug 修复)
│
└── hotfix/security-patch (紧急修复)
分支最佳实践
git checkout main
git pull origin main
git checkout -b feature/user-auth
git add .
git commit -m "feat(auth): add login endpoint"
git fetch origin main
git rebase origin/main
git push origin feature/user-auth
Pull Request 最佳实践
PR 标题格式
与 Conventional Commits 保持一致：
feat(auth): add OAuth2 login support
fix(api): resolve timeout issue
docs(readme): update installation guide
PR 描述模板
## 📝 变更类型
- [x] ✨ feat 新功能
- [ ] 🐛 fix Bug修复
- [ ] ♻️ refactor 重构
- [ ] 📚 docs 文档
- [ ] 💄 style 代码格式
- [ ] ⚡ perf 性能优化
- [ ] ✅ test 测试
- [ ] 🔧 chore 构建/工具
## 🎯 变更说明
<!-- 简要描述这个 PR 的目的和实现方式 -->
这个 PR 实现了用户认证功能，包括：
- JWT token 生成和验证
- 登录/登出端点
- 中间件保护路由
## 🔄 变更内容
<!-- 列出主要的文件变更 -->
- `src/auth/login.py` - 登录逻辑
- `src/auth/middleware.py` - 认证中间件
- `tests/test_auth.py` - 测试用例
## 🧪 测试
<!-- 描述测试情况 -->
- [x] 添加了单元测试
- [x] 添加了集成测试
- [x] 手动测试通过
- [ ] 性能测试通过
## ✅ 检查清单
<!-- 完成前确认 -->
- [x] 代码符合团队规范
- [x] 自我审查完成
- [x] 注释充分且准确
- [x] 文档已更新
- [x] 测试覆盖充分
- [x] 无合并冲突
## 📸 截图/演示
<!-- 如果适用，添加截图或 GIF -->
## 🔗 相关链接
- Closes #123
- Related #456
- Depends on #789
## ⚠️ 注意事项
<!-- 审查者需要注意的事项 -->
需要特别注意 JWT secret 的配置，已在 .env.example 中说明。
PR 审查响应
## 审查反馈
### 需要修改
- [ ] 安全问题：SQL 注入风险 (user_service.py:45)
- [ ] 性能问题：N+1 查询 (api.py:78)
### 建议改进
- [ ] 命名：`d()` → `double_value()` (utils.py:12)
- [ ] 注释：补充复杂逻辑说明 (payment.py:34)
### LGTM with suggestions
- [ ] 可以合并，但建议后续优化
Git Hooks 自动化
Pre-commit Hook
#!/bin/bash
npm run lint
if [ $? -ne 0 ]; then
echo "❌ Lint failed, please fix before committing"
exit 1
fi
npm test
if [ $? -ne 0 ]; then
echo "❌ Tests failed, please fix before committing"
exit 1
fi
echo "✅ Pre-commit checks passed"
Commit Message Hook
#!/bin/bash
commit_regex='^(feat|fix|docs|style|refactor|perf|test|chore|revert)(\(.+\))?: .{1,50}'
if ! grep -qE "$commit_regex" "$1"; then
echo "❌ Invalid commit message format"
echo "✅ Expected format: <type>(<scope>): <subject>"
exit 1
fi
echo "✅ Commit message format valid"
常见操作
修改最后一次提交
git add forgotten_file.py
git commit --amend
git commit --amend --no-edit
撤销提交
git reset --soft HEAD~1
git reset --hard HEAD~1
git reset --soft HEAD~3
交互式变基
git rebase -i HEAD~3
解决合并冲突
git rebase origin/main
git status
git add <resolved-files>
git rebase --continue
git rebase --abort
验证清单
提交或 PR 前，检查：
相关参考
