git-workflow@1.0.0

CLI 安装指南

通过 SkillSPAI CLI 一键安装到你的 AI 编码工具：

npm install -g skillspai

# Codex CLI
skillspai install git-workflow --target codex

# Claude Code
skillspai install git-workflow --target claude

# Cursor
skillspai install git-workflow --target cursor

# Windsurf
skillspai install git-workflow --target windsurf

# OpenCode
skillspai install git-workflow --target opencode

skillspai install git-workflow@1.0.0 --target claude

Skill 内容

# Git 工作流规范

## 分支策略

### Git Flow（适合发版项目）
```
main        ──── 生产环境代码
  └── develop ── 开发主线
       ├── feature/xxx ── 功能分支
       ├── bugfix/xxx  ── 修复分支
       └── release/x.x ── 发版分支
```

### GitHub Flow（适合持续部署）
```
main        ──── 生产环境代码
  └── feature/xxx ── 功能分支，合并后即部署
```

### 分支命名
```
feature/user-auth
feature/TICKET-123-add-search
bugfix/login-crash
hotfix/security-patch
release/v2.1.0
```

## Commit 规范

### Conventional Commits
```
<type>(<scope>): <description>

[optional body]

[optional footer]
```

### Type 类型
```
feat:     新功能
fix:      修复 bug
docs:     文档变更
style:    格式（不影响代码运行）
refactor: 重构（不是新功能也不是修 bug）
perf:     性能优化
test:     添加/修改测试
chore:    构建、工具、依赖变更
ci:       CI/CD 配置变更
```

### 示例
```
feat(auth): 添加 GitHub OAuth 登录

- 集成 passport-github2
- 添加 /api/auth/login 和 /api/auth/callback 路由
- Session 持久化到 SQLite

Closes #42
```

```
fix(api): 修复分页查询偏移量计算错误

offset 应为 (page - 1) * size，之前写成了 page * size

Fixes #108
```

### Commit 禁忌
- ❌ `fix bug`（太模糊）
- ❌ `update code`（不知道改了什么）
- ❌ `WIP`（不要提交半成品到共享分支）
- ❌ 一个 commit 改 500 行（拆分）

## Pull Request

### PR 标题
```
feat: 添加用户搜索功能
fix: 修复空指针异常
refactor: 重构数据库连接池
```

### PR 描述模板
```markdown
## 变更说明
- 做了什么
- 为什么这么做

## 测试
- [ ] 单元测试通过
- [ ] 手动测试通过

## 截图（UI 变更）
[截图]

## 关联 Issue
Closes #123
```

### Code Review 要点
- 逻辑是否正确
- 边界条件是否处理
- 是否有安全风险
- 命名是否清晰
- 是否有不必要的复杂度

### Review 原则
- 对事不对人，提建设性意见
- 区分 "必须改" 和 "建议改"
- 承认好的设计决策
- 小 PR（< 400 行）更容易 review

## 标签管理

### 语义化版本
```
v1.0.0  ── 首次发布
v1.1.0  ── 新功能（向后兼容）
v1.1.1  ── Bug 修复
v2.0.0  ── 不兼容的重大变更
```

### 打标签
```bash
git tag -a v1.2.0 -m "Release v1.2.0: 添加搜索功能"
git push origin v1.2.0
```

## .gitignore 必备项

```gitignore
# 依赖
node_modules/
__pycache__/
.venv/

# 环境变量
.env
.env.local
.env.*.local

# 构建产物
dist/
build/
*.pyc

# IDE
.vscode/
.idea/
*.swp

# 系统
.DS_Store
Thumbs.db

# 测试覆盖率
coverage/
htmlcov/

# 数据库
*.db
*.sqlite
```

## 常用 Git 命令

### 撤销
```bash
# 撤销工作区修改
git checkout -- <file>

# 撤销暂存
git restore --staged <file>

# 撤销上一次 commit（保留修改）
git reset --soft HEAD~1

# 修改上一次 commit message
git commit --amend
```

### 分支管理
```bash
# 创建并切换分支
git checkout -b feature/xxx

# 删除本地分支
git branch -d feature/xxx

# 删除远程分支
git push origin --delete feature/xxx

# 查看分支图
git log --oneline --graph --all
```

### 同步
```bash
# 拉取并变基
git pull --rebase origin main

# 交互式变基（整理 commit）
git rebase -i HEAD~3
```

## 常见错误

- ❌ 直接在 main 上开发 → ✅ 创建功能分支
- ❌ 一个 PR 改 20 个文件 → ✅ 拆分为小 PR
- ❌ commit message 写 "fix" → ✅ 写清楚修了什么
- ❌ 不写 PR 描述 → ✅ 说明改了什么、为什么
- ❌ 强制推送到共享分支 → ✅ 只在自己的功能分支 force push
- ❌ 合并冲突手动复制粘贴 → ✅ 用 git merge/rebase 解决