---

name: git-workflow description: Git 工作流模式，包括分支策略、提交规范、合并与变基、冲突解决，以及适用于各种规模团队的协作开发最佳实践。 origin: ECC

Git 工作流模式

Git 版本控制、分支策略和协作开发的最佳实践。

何时激活

• 为新项目设置 Git 工作流
• 决定分支策略（GitFlow、主干开发、GitHub flow）
• 编写提交信息和 PR 描述
• 解决合并冲突
• 管理发布和版本标签
• 为新团队成员培训 Git 实践

分支策略

GitHub Flow（简单，推荐大多数团队使用）

最适合持续部署和中小型团队。

main (受保护，始终可部署)
  │
  ├── feature/user-auth      → PR → 合并到 main
  ├── feature/payment-flow   → PR → 合并到 main
  └── fix/login-bug          → PR → 合并到 main

规则：

• main 始终可部署
• 从 main 创建功能分支
• 准备好审查时打开 Pull Request
• 通过审批和 CI 后，合并到 main
• 合并后立即部署

主干开发（高速迭代团队）

最适合拥有强大 CI/CD 和功能开关的团队。

main (主干)
  │
  ├── 短期功能分支 (最多1-2天)
  ├── 短期功能分支
  └── 短期功能分支

规则：

• 所有人直接提交到 main 或使用极短期分支
• 功能开关隐藏未完成的工作
• 合并前 CI 必须通过
• 每天多次部署

GitFlow（复杂，基于发布周期）

最适合计划性发布和企业项目。

main (生产发布)
  │
  └── develop (集成分支)
        │
        ├── feature/user-auth
        ├── feature/payment
        │
        ├── release/1.0.0    → 合并到 main 和 develop
        │
        └── hotfix/critical  → 合并到 main 和 develop

规则：

• main 仅包含生产就绪代码
• develop 是集成分支
• 功能分支从 develop 创建，合并回 develop
• 发布分支从 develop 创建，合并到 main 和 develop
• 热修复分支从 main 创建，合并到 main 和 develop

如何选择

| 策略 | 团队规模 | 发布频率 | 最适合 | |------|----------|----------|--------| | GitHub Flow | 任意 | 持续 | SaaS、Web 应用、初创公司 | | 主干开发 | 5+ 有经验 | 每天多次 | 高速迭代团队、功能开关 | | GitFlow | 10+ | 计划性 | 企业、受监管行业 |

提交信息

约定式提交格式

<type>(<scope>): <subject>

[可选正文]

[可选脚注]

类型

| 类型 | 用途 | 示例 | |------|------|------| | feat | 新功能 | feat(auth): add OAuth2 login | | fix | 修复缺陷 | fix(api): handle null response in user endpoint | | docs | 文档 | docs(readme): update installation instructions | | style | 格式化，无代码变更 | style: fix indentation in login component | | refactor | 代码重构 | refactor(db): extract connection pool to module | | test | 添加/更新测试 | test(auth): add unit tests for token validation | | chore | 维护任务 | chore(deps): update dependencies | | perf | 性能优化 | perf(query): add index to users table | | ci | CI/CD 变更 | ci: add PostgreSQL service to test workflow | | revert | 回退之前的提交 | revert: revert "feat(auth): add OAuth2 login" |

好与坏的示例

# 差：模糊，没有上下文
git commit -m "fixed stuff"
git commit -m "updates"
git commit -m "WIP"

# 好：清晰、具体、解释原因
git commit -m "fix(api): retry requests on 503 Service Unavailable

The external API occasionally returns 503 errors during peak hours.
Added exponential backoff retry logic with max 3 attempts.

Closes #123"

提交信息模板

在仓库根目录创建 .gitmessage：

# <type>(<scope>): <subject>
# # Types: feat, fix, docs, style, refactor, test, chore, perf, ci, revert
# Scope: api, ui, db, auth, etc.
# Subject: imperative mood, no period, max 50 chars
#
# [optional body] - explain why, not what
# [optional footer] - Breaking changes, closes #issue

启用方式：git config commit.template .gitmessage

合并与变基

合并（保留历史）

# 创建合并提交
git checkout main
git merge feature/user-auth

# 结果：
# *   merge commit
# |\
# | * feature commits
# |/
# * main commits

适用场景：

• 将功能分支合并到 main
• 需要保留完整历史记录
• 多人在该分支上协作
• 分支已推送且他人可能基于此分支工作

变基（线性历史）

# 将功能提交重写到目标分支上
git checkout feature/user-auth
git rebase main

# 结果：
# * feature commits (重写后)
# * main commits

适用场景：

• 更新本地功能分支