git-workflow · diff

git:20260905.a346b91 to git:20260906.d2681a7

5 added, 5 removed. Audit A to A.

---

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 工作流专家

## 核心理念

**良好的 Git 实践** 是团队协作的基础：

```

┌─────────────────────────────────────────────────────────┐

│ 规范提交 → 清晰历史 → 易于回溯 → 高效协作 │

└─────────────────────────────────────────────────────────┘

```

**核心原则**：

- ✅ **提交历史即文档**

- ✅ **原子提交，单一职责**

- ✅ **清晰的可追溯性**

- ✅ **易于 Code Review**

---

## 何时使用本技能

在以下场景时激活：

- 需要 Git 提交（commit）

- 创建 Pull Request / Merge Request

- 代码分支管理

- 版本发布

- 提到"git"、"提交"、"分支"、"PR"

---

## Conventional Commits 规范

### 提交格式

```

<body>

```

### 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)` |

### 提交示例

```bash

# 简单提交

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.

+ 使用 Stripe API 实现信用卡支付处理。

+ 增加用于更新支付状态的 webhook 处理。

- Add Stripe client initialization

- Implement payment intent creation

- Add webhook endpoint for status updates

- Handle payment success/failure scenarios

Closes #123

Related #456

```

---

## 提交最佳实践

### 1. 原子提交原则

```bash

# ❌ 不好的做法：一次提交多个变更

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. 提交信息质量

```bash

# ❌ 不好的提交信息

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

```

### 分支最佳实践

```bash

# 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 保持一致：

```markdown

feat(auth): add OAuth2 login support

fix(api): resolve timeout issue

docs(readme): update installation guide

```

### PR 描述模板

```markdown

## 📝 变更类型

- [x] ✨ feat 新功能

- [ ] 🐛 fix Bug修复

- [ ] ♻️ refactor 重构

- [ ] 📚 docs 文档

- [ ] 💄 style 代码格式

- [ ] ⚡ perf 性能优化

- [ ] ✅ test 测试

- [ ] 🔧 chore 构建/工具

## 🎯 变更说明

这个 PR 实现了用户认证功能，包括：

- JWT token 生成和验证

- 登录/登出端点

- 中间件保护路由

## 🔄 变更内容

- `src/auth/login.py` - 登录逻辑

- `src/auth/middleware.py` - 认证中间件

- `tests/test_auth.py` - 测试用例

## 🧪 测试

- [x] 添加了单元测试

- [x] 添加了集成测试

- [x] 手动测试通过

- [ ] 性能测试通过

## ✅ 检查清单

- [x] 代码符合团队规范

- [x] 自我审查完成

- [x] 注释充分且准确

- [x] 文档已更新

- [x] 测试覆盖充分

- [x] 无合并冲突

## 📸 截图/演示

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

## 🔗 相关链接

- Closes #123

- Related #456

- Depends on #789

## ⚠️ 注意事项

需要特别注意 JWT secret 的配置，已在 .env.example 中说明。

```

### PR 审查响应

```markdown

## 审查反馈

### 需要修改

- [ ] 安全问题：SQL 注入风险 (user_service.py:45)

- [ ] 性能问题：N+1 查询 (api.py:78)

### 建议改进

- [ ] 命名：`d()` → `double_value()` (utils.py:12)

- [ ] 注释：补充复杂逻辑说明 (payment.py:34)

- ### LGTM with suggestions

+ ### LGTM（附带建议）

- [ ] 可以合并，但建议后续优化

```

---

## Git Hooks 自动化

- ### Pre-commit Hook

+ ### 提交前钩子

```bash

#!/bin/bash

# .git/hooks/pre-commit

# 运行 linter

npm run lint

if [ $? -ne 0 ]; then

echo "❌ Lint failed, please fix before committing"

exit 1

# 运行测试

npm test

if [ $? -ne 0 ]; then

echo "❌ Tests failed, please fix before committing"

exit 1

echo "✅ Pre-commit checks passed"

```

- ### Commit Message Hook

+ ### 提交消息钩子

```bash

#!/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

echo "✅ Commit message format valid"

```

---

## 常见操作

### 修改最后一次提交

```bash

# 添加遗漏的文件

git add forgotten_file.py

# 修改提交信息

git commit --amend

# 修改提交内容但不改信息

git commit --amend --no-edit

```

### 撤销提交

```bash

# 撤销最后一次提交（保留变更）

git reset --soft HEAD~1

# 撤销最后一次提交（丢弃变更）

git reset --hard HEAD~1

# 撤销多次提交

git reset --soft HEAD~3

```

### 交互式变基

```bash

# 变基最近 3 个提交

git rebase -i HEAD~3

# 命令：

# pick - 保留提交

# reword - 修改提交信息

# edit - 编辑提交

# squash - 合并到前一个提交

# drop - 删除提交

```

### 解决合并冲突

```bash

# 1. 开始变基

git rebase origin/main

# 2. 遇到冲突时

git status # 查看冲突文件

# 3. 手动解决冲突

# 编辑冲突文件，删除 <<<<<<< ======= >>>>>>> 标记

# 4. 标记冲突已解决

git add <resolved-files>

# 5. 继续变基

git rebase --continue

# 6. 如果需要放弃

git rebase --abort

```

---

## 验证清单

提交或 PR 前，检查：

- [ ] 提交信息符合 Conventional Commits 规范

- [ ] 每个提交职责单一

- [ ] 提交大小合理（< 400 行）

- [ ] 分支命名符合规范

- [ ] 无敏感信息泄露

- [ ] 关联 Issue/PR

- [ ] 代码已通过测试

- [ ] 文档已更新

---

## 相关参考

- [Git 工作流规范](../references/git-workflow.md)

- [Conventional Commits](https://www.conventionalcommits.org/)

## 约束

### 公共硬约束

本块由 `docs/templates/skill-common-constraints.md` 统一维护；每个 `SKILL.md` 的 `## 约束` 必须逐字同步本块，不得在副本中改写公共规则。

- 任务需要落盘时，使用唯一的 `./.bensz-api/task-{yyyymmdd-hhmm}-{简短描述}/` 根目录；共享材料放入 `shared/`，Skill 专属材料放入该 Skill 的 `input/`、`output/`、`log/`。

- 正式交付物、源代码和正式计划按项目约定保存，不写入任务工作区；未经授权不覆盖、删除、迁移或远程写入。

- 项目维护变更检查 BAC 可用性并记录需求、AI 产出、工具结果、文件改动和验证摘要；BAC 只做过程审计，不替代署名、责任或合规判断。

- 不记录 API Key、访问令牌、密码、Cookie、环境/凭据文件、私有 Prompt、身份信息、本地用户名、主机名或不必要的大体积原始数据。

- 文件路径必须规范化并限制在授权项目范围内；外部 URL、子进程和网络访问遵循最小权限，防止路径遍历、SSRF 和命令注入。

- Skill 版本唯一记录在自身 `config.yaml:skill_info.version`；公开 API、协议、目录或配置变更同步文档与 `CHANGELOG.md`。

- `bensz-collect-bugs` 是一个 Agent Skill；仅将 Bensz Agent Skill 或 Bensz 基础设施本身的设计缺陷交给它。先脱敏写入 `~/.bensz-skills/bugs/`，当前任务不中断，只有用户明确要求才公开上报，禁止直接修改用户已安装的 Skill 源码。