Via CLI Git Flow 工作流

基于 Git Flow 的简化分支管理方案，支持功能开发、预发布、生产发布和热修复的完整流程。

� 文档导航

• 📖 完整工作流方案 - 详细的 Git Flow 工作流程、分支策略和最佳实践（当前文档）
• 🚀 快速使用指南 - 5 分钟快速上手，日常命令速查
• 📝 变更日志 - 版本更新记录

快速开始： 如果你是第一次使用，建议先阅读 快速使用指南

�📋 目录

• 核心概念
• 分支策略
• 工作流程
• 命令参考
• 最佳实践
• 常见问题

🎯 核心概念

分支模型

Via CLI Git Flow 采用简化的分支模型，包含以下核心分支：

master/main (生产分支)
    ↑
    │ merge + tag
    │
release/* (发布分支)
    ↑
    │ create from
    │
pre (预发布分支)
    ↑
    │ rebase + fast-forward
    │
dev (开发分支)
    ↑
    │ rebase + fast-forward
    │
feature/* (功能分支)

合并策略

关键特性：使用 Rebase + Fast-Forward 保持线性历史

1. Feature → Dev: 在 feature 分支执行 rebase dev，然后快速合并到 dev
2. Dev → Pre: 在 dev 分支执行 rebase pre，然后快速合并到 pre
3. Pre → Master: 普通合并，创建 tag 和 release 分支
4. Hotfix: 合并到 pre，dev 执行 rebase pre

优势：

• ✅ 保持主分支历史线性清晰
• ✅ 每个功能一个明确的提交
• ✅ 易于追溯和回滚
• ✅ 减少合并冲突

🌳 分支策略

长期分支

| 分支 | 用途 | 保护级别 | 部署环境 | |------|------|----------|----------| | master/main | 生产稳定版本 | 🔒 最高 | 生产环境 | | pre | 预发布测试 | 🔒 高 | 预发布环境 | | dev | 开发集成 | 🔒 中 | 开发环境 |

临时分支

| 分支前缀 | 用途 | 生命周期 | 来源 | 合并目标 | |---------|------|---------|------|---------| | feature/* | 功能开发 | 短期 | 当前分支 | dev | | hotfix/* | 紧急修复 | 短期 | master/release | pre | | release/* | 版本发布 | 中期 | master | - |

分支命名规范

# 功能分支
feature/user-login
feature/payment-integration
feature/JIRA-1234-description

# 热修复分支
hotfix/critical-bug
hotfix/security-patch
hotfix/PROD-5678

# 发布分支（自动生成，使用日期）
release/20251027
release/20251105

🔄 工作流程

1️⃣ 功能开发流程

场景： 开发新功能

# 步骤 1: 创建功能分支
via-cli git feature user-login
# ✅ 创建并切换到 feature/user-login
# ✅ 可选推送到远程

# 步骤 2: 开发功能
# ... 在 feature/user-login 分支上进行开发

# 步骤 3: 提交代码（智能规范化提交）
via-cli git commit
# ✅ 自动检查未暂存的文件
# ✅ 选择提交类型（feat, fix, docs 等）
# ✅ 输入提交信息
# ✅ 可选添加 #release# 触发 CI/CD

# 步骤 4: 合并到 dev（自动 rebase + 快速合并）
via-cli git dev
# ✅ 在 feature 分支执行 rebase dev
# ✅ 切换到 dev 分支
# ✅ 快速合并 feature 分支
# ✅ 推送到远程 dev
# ✅ 可选删除 feature 分支

# 结果：dev 分支包含新功能，历史保持线性

流程图：

feature/user-login    ●──●──●
                            │ rebase dev
                            ↓
dev                   ●──●──●──●
                                │ fast-forward merge
                                ↓
dev (updated)         ●──●──●──●──●

2️⃣ 预发布流程

场景： 将开发完成的功能部署到预发布环境测试

# 确保在 dev 分支
git checkout dev

# 合并到 pre（自动 rebase + 快速合并）
via-cli git pre
# ✅ 在 dev 分支执行 rebase pre
# ✅ 切换到 pre 分支
# ✅ 快速合并 dev 分支
# ✅ 推送到远程 pre
# ✅ 自动切回 dev 分支

# 结果：pre 分支包含 dev 的所有功能，可以部署到预发布环境测试

流程图：

dev     ●──●──●──●──●
              │ rebase pre
              ↓
pre     ●──●──●
              │ fast-forward merge
              ↓
pre     ●──●──●──●──●──●

3️⃣ 生产发布流程

场景： 将预发布测试通过的版本发布到生产环境

# 创建 release（从 pre 合并到 master，打 tag，创建 release 分支）
via-cli git release

# 交互式输入：
# 请输入发布版本号（默认使用日期 20251027）: [回车或输入自定义版本号]

# ✅ 切换到 master 并更新
# ✅ 检查 release 分支是否存在
# ✅ 合并 pre 到 master
# ✅ 创建 tag（如 20251027）
# ✅ 从 master 创建 release 分支（如 release/20251027）
# ✅ 推送 master、tag 和 release 分支到远程

# 结果：
# - master 分支更新到最新版本
# - 创建了版本 tag（用于部署）
# - 创建了 release 分支（用于后续的 hotfix）

流程图：

pre           ●──●──●──●──●
                    │ merge
                    ↓
master        ●──●──●──●
                    │ create tag (20251027)
                    │ create release branch
                    ↓
release/20251027  ●──●──●──●

版本标签规则：

• 默认使用日期格式：YYYYMMDD（如 20251027）
• 也支持自定义版本号（如 v1.2.0、2024-Q4-Release1）
• 使用 tag 进行生产部署：git checkout 20251027

4️⃣ 热修复流程

场景： 生产环境出现紧急问题需要快速修复

# 步骤 1: 创建 hotfix 分支
via-cli git hotfix critical-bug

# 交互式选择源分支：
# 1. release/20251027 (release 分支) [推荐]
# 2. main (主分支)
# 选择: 1

# ✅ 从 release 分支创建 hotfix/critical-bug
# ✅ 可选推送到远程

# 步骤 2: 修复问题
git add .
git commit -m "fix: 修复关键bug"

# 步骤 3: 完成 hotfix
via-cli git hotfix-finish

# ✅ 合并到 pre 分支
# ✅ 在 dev 分支执行 rebase pre（同步修复）
# ✅ 删除 hotfix 分支
# ✅ 推送所有更改到远程

# 结果：
# - 修复已合并到 pre（可以重新发布）
# - dev 分支已同步修复（避免下次发布又出现问题）

流程图：

release/20251027   ●──●
                      │ create hotfix
                      ↓
hotfix/critical    ●──●──●
                         │ merge to pre
                         ↓
pre               ●──●──●──●
                         │ dev rebase pre
                         ↓
dev               ●──●──●──●──●

5️⃣ 撤销操作

场景： 需要撤销最近的提交

via-cli git undo

# 交互式选择：
# 1. 软撤销：撤销提交，保留更改（可以重新提交）
# 2. 硬撤销：完全删除提交和更改（慎用！）

# 软撤销示例：
# ✅ 提交被撤销
# ✅ 更改保留在工作区
# ✅ 可以修改后重新提交

# 硬撤销示例：
# ⚠️  提交和更改都被删除
# ⚠️  无法恢复

6️⃣ 状态检查

场景： 检查当前 Git 状态和冲突

via-cli git status

# 显示信息：
# ✅ 当前分支
# ✅ 冲突文件列表
# ✅ 未暂存的更改
# ✅ 已暂存的更改
# ✅ 本地领先/落后远程的提交数

📖 命令参考

完整命令列表

# 功能开发
via-cli git feature <name>        # 创建功能分支
via-cli git commit                # 智能规范化提交
via-cli git dev                   # 合并到 dev（rebase + 快速合并）

# 预发布
via-cli git pre                   # 合并到 pre（rebase + 快速合并）

# 生产发布
via-cli git release               # 创建 release（合并到 master + tag）

# 热修复
via-cli git hotfix <name>         # 创建 hotfix 分支
via-cli git hotfix-finish         # 完成 hotfix

# 工具命令
via-cli git undo                  # 撤销提交
via-cli git status                # 检查状态
via-cli git                       # 显示帮助

命令详解

via-cli git feature <name>

功能： 创建功能分支

参数：

• <name>: 功能分支名称（可选，如果不提供会提示输入）

选项：

• --branch <name>: 通过选项指定分支名

示例：

via-cli git feature user-login
via-cli git feature JIRA-1234
via-cli git feature --branch payment

交互流程：

1. 如果未提供名称，提示输入功能分支名称
2. 创建并切换到 feature/<name> 分支
3. 询问是否推送到远程

via-cli git commit

功能： 智能规范化提交代码

工作流程：

1. 自动检查是否有未暂存的文件（unstaged changes）
   • 如果有，提示确认是否暂存（git add）
2. 选择提交类型（遵循语义化提交规范）
   • feat: ✨ 新功能
   • fix: 🐛 修复 bug
   • docs: 📝 文档更新
   • style: 💄 代码格式调整
   • refactor: ♻️ 重构
   • perf: ⚡ 性能优化
   • test: ✅ 测试相关
   • build: 📦 构建系统
   • ci: 🎡 CI/CD 配置
   • chore: 🔧 杂项任务
   • revert: ⏪ 回退代码
3. 输入提交信息（简短清晰）
4. 可选添加 #release# 后缀
   • 添加后会触发 CI/CD 自动部署流程
5. 确认并执行提交
6. 询问是否推送到远程

示例：

via-cli git commit

# 交互流程：
# 1. 发现未暂存文件: src/login.ts, src/utils.ts
#    → 是否暂存这些文件? (Y/n): Y
# 2. 选择提交类型:
#    → ✨ feat: 新功能
# 3. 输入提交信息:
#    → 实现用户登录功能
# 4. 是否添加 #release# 触发自动部署?
#    → (y/N): n
# 5. 确认提交信息:
#    feat: 实现用户登录功能
#    → 确认提交? (Y/n): Y
# 6. 是否推送到远程?
#    → (Y/n): Y
#
# 结果: feat: 实现用户登录功能

#release# 触发器说明：

• 在提交信息末尾添加 #release# 后缀会触发 CI/CD 自动部署
• 适用场景：
  • 功能开发完成，需要立即部署到测试环境
  • 紧急 bug 修复，需要快速发布
  • 自动化发布流程中的标记提交
• 示例提交信息：fix: 修复支付接口超时问题 #release#

更多详情： 查看 COMMIT_GUIDE.md 获取完整的提交规范和最佳实践

via-cli git dev

功能： 将当前分支（通常是 feature）合并到 dev

工作流程：

1. 检查当前分支（建议在 feature 分支执行）
2. 确保 dev 分支存在（不存在则创建）
3. 在当前分支执行 rebase dev
4. 切换到 dev 分支并更新
5. 使用快速合并（fast-forward）合并当前分支
6. 推送到远程 dev
7. 询问是否删除 feature 分支

冲突处理：

• Rebase 冲突：提供手动解决、取消、跳过选项
• 快速合并失败：提示确保已正确 rebase

via-cli git pre

功能： 将 dev 分支合并到 pre

工作流程：

1. 检查当前分支（建议在 dev 分支执行）
2. 确保 pre 分支存在（不存在则创建）
3. 在 dev 分支执行 rebase pre
4. 切换到 pre 分支并更新
5. 使用快速合并（fast-forward）合并 dev
6. 推送到远程 pre
7. 切回 dev 分支

via-cli git release

功能： 从 pre 创建 release 分支并发布到 master

工作流程：

1. 提示输入版本号（默认使用当天日期 YYYYMMDD）
2. 切换到 master/main 分支并更新
3. 检查 release 分支和 tag 是否已存在
4. 合并 pre 到 master
5. 创建版本 tag
6. 从 master 创建 release 分支
7. 询问是否推送到远程

示例：

via-cli git release
# 输入版本号: 20251027 （或直接回车使用默认日期）

via-cli git hotfix <name>

功能： 创建热修复分支

源分支选择：

• 优先从 release 分支创建（推荐）
• 如果没有 release 分支，从 master/main 创建

工作流程：

1. 如果未提供名称，提示输入 hotfix 名称
2. 如果存在 release 分支，提示选择源分支
3. 切换到源分支并更新
4. 创建并切换到 hotfix/<name> 分支
5. 询问是否推送到远程

via-cli git hotfix-finish

功能： 完成热修复流程

要求： 必须在 hotfix 分支执行

工作流程：

1. 检查当前分支是否为 hotfix 分支
2. 切换到 pre 分支并合并 hotfix
3. 切换到 dev 分支执行 rebase pre
4. 删除本地 hotfix 分支
5. 询问是否推送所有更改到远程
6. 推送 pre、dev 分支和删除远程 hotfix 分支

via-cli git undo

功能： 撤销最近的提交

选项：

• 软撤销（soft）: 撤销提交但保留更改在工作区
• 硬撤销（hard）: 完全删除提交和更改（⚠️ 危险操作）

使用场景：

• 提交信息写错了
• 提交了错误的文件
• 需要修改提交内容

via-cli git status

功能： 检查 Git 状态和冲突

显示信息：

• 当前分支名称
• 冲突文件列表（如果有）
• 未暂存的更改
• 已暂存的更改
• 本地领先/落后远程的提交数

冲突文件会显示解决步骤：

1. 编辑冲突文件，解决冲突标记
2. git add .
3. git commit

🔧 冲突处理

合并冲突处理

当执行合并操作遇到冲突时，系统会提供以下选项：

请选择如何处理冲突：
1. 手动解决冲突（推荐）
2. 使用当前分支的版本
3. 使用目标分支的版本
4. 取消合并

选项 1: 手动解决冲突（推荐）

步骤：

1. 系统会显示冲突文件列表
2. 询问是否在 VS Code 中打开冲突文件
3. 编辑文件，查找并解决冲突标记：

   <<<<<<< HEAD
   当前分支的代码
   =======
   合并分支的代码
   >>>>>>> branch-name

4. 删除冲突标记，保留需要的代码
5. 执行：

   git add .
   git commit

选项 2: 使用当前分支的版本

自动选择当前分支的所有更改，忽略目标分支的更改。

选项 3: 使用目标分支的版本

自动选择目标分支的所有更改，忽略当前分支的更改。

选项 4: 取消合并

取消本次合并操作，恢复到合并前的状态。

Rebase 冲突处理

当执行 rebase 操作遇到冲突时：

请选择如何处理 rebase 冲突：
1. 手动解决冲突（推荐）
2. 取消 rebase
3. 跳过当前提交

手动解决步骤：

1. 编辑冲突文件，解决冲突标记
2. 执行：

   git add .
   git rebase --continue

3. 重新运行被中断的命令

取消 rebase：

git rebase --abort

跳过当前提交：

git rebase --skip

💡 最佳实践

1. 提交规范

使用语义化的提交信息：

feat: 添加用户登录功能
fix: 修复支付失败问题
docs: 更新 API 文档
style: 代码格式化
refactor: 重构用户模块
test: 添加单元测试
chore: 更新依赖包

2. 分支管理

DO ✅

• 功能开发完成后及时合并并删除 feature 分支
• 保持 dev、pre、master 分支的线性历史
• 定期同步远程分支
• Hotfix 完成后立即删除分支

DON'T ❌

• 不要直接在 dev、pre、master 分支开发
• 不要在 feature 分支长期存在（超过2周）
• 不要手动合并，使用 via-cli 命令确保流程正确
• 不要跳过 rebase 步骤直接合并

3. 发布流程

每日构建（Daily Build）

# 1. 所有功能合并到 dev
via-cli git dev

# 2. 部署到开发环境测试
# ... 自动化部署 dev 分支

预发布（Pre-Release）

# 1. dev 测试通过后合并到 pre
via-cli git pre

# 2. 部署到预发布环境
# ... 自动化部署 pre 分支

# 3. 进行全面测试

生产发布（Production Release）

# 1. pre 测试通过后创建 release
via-cli git release

# 2. 使用 tag 部署到生产环境
git checkout 20251027
# ... 自动化部署

# 3. 监控生产环境

4. 团队协作

开发者工作流：

1. 从最新的 dev 分支创建 feature
2. 完成开发后合并到 dev
3. 等待 QA 测试

测试工程师工作流：

1. 在 dev 环境测试新功能
2. 在 pre 环境进行集成测试
3. 在生产环境验证发布

发布经理工作流：

1. 协调 feature 合并到 dev
2. 定期将 dev 合并到 pre
3. 确认测试通过后执行 release
4. 处理紧急 hotfix

5. 版本管理

版本号规则：

• 日期版本（推荐）: YYYYMMDD (如 20251027)

  • 优势：直观、唯一、自动生成
  • 适用：频繁发布、敏捷开发

• 语义版本: v{major}.{minor}.{patch} (如 v1.2.3)

  • 优势：明确版本变更类型
  • 适用：正式产品、API 版本管理

Release 分支保留策略：

• 保留最近 3 个 release 分支用于 hotfix
• 超过 3 个月的 release 分支可以删除（tag 保留）

❓ 常见问题

Q1: 为什么使用 Rebase 而不是 Merge？

A: Rebase 的优势：

• ✅ 保持线性历史，便于追溯
• ✅ 每个功能一个清晰的提交点
• ✅ 易于回滚和 cherry-pick
• ✅ 减少无意义的 merge commit

注意： 只在未推送的本地分支使用 rebase，已推送的公共分支避免 rebase。

Q2: Rebase 冲突了怎么办？

A: 按照提示步骤操作：

1. 使用 via-cli git status 查看冲突文件
2. 编辑文件解决冲突
3. 执行 git add .
4. 执行 git rebase --continue
5. 重新运行被中断的命令

如果不确定，可以选择 "取消 rebase"，然后寻求帮助。

Q3: 快速合并失败怎么办？

A: 快速合并失败说明分支历史不是线性的，可能原因：

• Rebase 步骤被跳过
• 在错误的分支执行命令
• 目标分支有新的提交

解决方案：

1. 确保在正确的分支
2. 重新执行 rebase 操作
3. 确保 rebase 成功后再执行合并

Q4: Hotfix 应该从哪个分支创建？

A: 优先级：

1. 最近的 release 分支（推荐）- 与生产环境完全一致
2. master/main 分支 - 如果没有 release 分支

创建时系统会自动提示选择。

Q5: 为什么 dev 要 rebase pre 而不是相反？

A: 这是为了保持分支的优先级：

• pre 是更稳定的分支，接近生产
• dev 是频繁变更的分支
• dev rebase pre 意味着：将 dev 的新功能建立在 pre 的基础上
• 这样 pre 的历史保持稳定，便于追溯

Q6: 可以跳过 dev/pre 直接发布吗？

A: 不推荐，但紧急情况可以：

# 紧急情况：直接从 feature 发布
git checkout pre
git merge feature/urgent-fix
git checkout master
git merge pre
git tag emergency-20251027

但这会破坏流程的完整性，后续需要手动同步 dev 分支。

Q7: 多个开发者同时在 dev 上工作怎么办？

A: Via CLI 的 Rebase + Fast-Forward 策略天然适合多人协作：

1. 开发者 A: 在 feature-A 分支开发
2. 开发者 B: 在 feature-B 分支开发
3. 开发者 A 先执行 via-cli git dev 合并
4. 开发者 B 执行 via-cli git dev 时会自动 rebase 最新的 dev
5. 历史保持线性，无需复杂的合并

Q8: 版本回退怎么做？

A: 使用 tag 进行版本回退：

# 查看所有版本
git tag

# 回退到指定版本
git checkout 20251025

# 如果要在此基础上修复并重新发布
via-cli git hotfix rollback-fix
# ... 修复后
via-cli git hotfix-finish

Q9: 如何查看某个功能在哪个版本发布的？

A: 由于使用线性历史，很容易追溯：

# 查看包含某个提交的所有 tag
git tag --contains <commit-hash>

# 查看某个文件的变更历史
git log --follow <file-path>

# 查看两个版本之间的差异
git log 20251025..20251027 --oneline

Q10: CI/CD 如何集成？

A: 推荐的 CI/CD 配置：

# .github/workflows/deploy.yml 示例
on:
  push:
    branches:
      - dev      # 自动部署到开发环境
      - pre      # 自动部署到预发布环境
    tags:
      - '*'      # 自动部署到生产环境

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v2
      
      - name: Deploy
        run: |
          if [[ $GITHUB_REF == refs/heads/dev ]]; then
            # 部署到开发环境
            ./deploy.sh dev
          elif [[ $GITHUB_REF == refs/heads/pre ]]; then
            # 部署到预发布环境
            ./deploy.sh pre
          elif [[ $GITHUB_REF == refs/tags/* ]]; then
            # 部署到生产环境
            ./deploy.sh prod
          fi

📚 相关资源

• Git Flow 原始论文
• GitHub Flow
• Atlassian Git Tutorials

🤝 贡献

欢迎提交 Issue 和 Pull Request 改进这个工作流！

📄 许可证

MIT License