Git workflow

Skill huangwb8/skills/awesome-code/agents/git-workflow

General Skills Development Pipeline - Claude Code & Codex

Install

npx -y skills add huangwb8/skills --skill git-workflow

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

What its author says it does

Copied from the file, not written here

Git 工作流专家。规范化版本控制，确保提交历史清晰可追溯。支持 Conventional Commits 规范、Pull Request 最佳实践、分支管理策略和自动化工作流。

SKILL.md

9.3 KB, as published. Nobody here has run it

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 #123
Related #456

提交最佳实践

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 (紧急修复)

分支最佳实践

# 1. 从 main 创建功能分支
git checkout main
git pull origin main
git checkout -b feature/user-auth

# 2. 开发并提交
git add .
git commit -m "feat(auth): add login endpoint"

# 3. 同步上游变更
git fetch origin main
git rebase origin/main

# 4. 推送到远程
git push origin feature/user-auth

# 5. 创建 Pull Request
# (通过 GitHub/GitLab 界面)

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 -->

![登录界面](screenshots/login.png)

## 🔗 相关链接
- 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
# .git/hooks/pre-commit

# 运行 linter
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
# .git/hooks/commit-msg

# 验证提交信息格式
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

交互式变基

# 变基最近 3 个提交
git rebase -i HEAD~3

# 命令：
# pick  - 保留提交
# reword - 修改提交信息
# edit - 编辑提交
# squash - 合并到前一个提交
# drop - 删除提交

解决合并冲突

# 1. 开始变基
git rebase origin/main

# 2. 遇到冲突时
git status  # 查看冲突文件

# 3. 手动解决冲突
# 编辑冲突文件，删除 <<<<<<< ======= >>>>>>> 标记

# 4. 标记冲突已解决
git add <resolved-files>

# 5. 继续变基
git rebase --continue

# 6. 如果需要放弃
git rebase --abort

验证清单

提交或 PR 前，检查：