name: git-storytelling-branch-strategy description: 用于规划Git分支策略或管理开发分支。通过有效的分支组织和工作流模式，帮助创建清晰的开发叙事。 allowed-tools:

Bash
Read

Git故事讲述 - 分支策略

这个技能帮助您实施有效的分支策略，通过组织良好、目的明确的分支管理来讲述开发过程的故事。好的分支策略能创建清晰的并行开发努力叙事。

核心概念

为什么分支策略重要

好的分支策略：

创建清晰的开发叙事 - 每个分支讲述一个特定的故事
支持并行工作 - 多个功能可以同时开发
便于代码审查 - 更改被隔离并可审查
支持部署工作流 - 不同环境使用不同分支
减少合并冲突 - 较小、集中的分支更容易合并
记录开发历史 - 分支名称和结构显示意图

分支的故事

将分支视为代码库中的并行故事线：

主分支：规范故事，始终可工作并可部署
功能分支：最终会合并到主故事的支线任务
发布分支：准备发布章节
热修复分支：发布故事的紧急补丁
开发分支：故事汇集的暂存区

分支命名约定

标准前缀

使用一致的前缀来分类分支：

feature/    - 新功能
fix/        - 错误修复
hotfix/     - 生产环境紧急修复
refactor/   - 代码重构
test/       - 测试更改
docs/       - 文档
chore/      - 维护任务
release/    - 发布准备

命名最佳实践

好的分支名称是：

# 好：清晰、描述性、短横线分隔
feature/user-authentication
fix/payment-processing-timeout
refactor/extract-validation-logic
hotfix/critical-security-patch

# 坏：模糊、不清晰、不一致
feature/new-stuff
fix-thing
my-branch
temp

包含问题编号

引用跟踪系统问题：

feature/123-add-user-authentication
fix/456-resolve-memory-leak
hotfix/789-patch-security-vulnerability

分支名称格式

遵循一致的模式：

<类型>/<问题编号>-<简短描述>

示例：
feature/234-oauth-integration
fix/567-null-pointer-exception
refactor/890-simplify-error-handling

常见分支策略

Git Flow

适用于基于发布的软件的健壮分支模型：

# 主分支（永久）
main        # 生产就绪代码
develop     # 功能集成分支

# 支持分支（临时）
feature/*   # 新功能
release/*   # 发布准备
hotfix/*    # 生产修复

Git Flow工作流：

# 启动新功能
git checkout develop
git checkout -b feature/user-profile

# 在功能上提交
git commit -m "feat: 添加用户配置文件模型"
git commit -m "feat: 添加配置文件更新端点"

# 完成功能
git checkout develop
git merge --no-ff feature/user-profile
git branch -d feature/user-profile

# 启动发布
git checkout develop
git checkout -b release/v1.2.0

# 准备发布
git commit -m "chore: 版本升级到1.2.0"
git commit -m "docs: 更新CHANGELOG"

# 完成发布
git checkout main
git merge --no-ff release/v1.2.0
git tag -a v1.2.0 -m "发布版本1.2.0"
git checkout develop
git merge --no-ff release/v1.2.0
git branch -d release/v1.2.0

# 紧急热修复
git checkout main
git checkout -b hotfix/v1.2.1

# 修复并发布
git commit -m "fix: 关键安全问题"
git checkout main
git merge --no-ff hotfix/v1.2.1
git tag -a v1.2.1 -m "热修复版本1.2.1"
git checkout develop
git merge --no-ff hotfix/v1.2.1
git branch -d hotfix/v1.2.1

GitHub Flow

适用于持续部署的简单模型：

# 只有一个主分支
main        # 始终可部署

# 所有工作都在功能分支
feature/*   # 功能、修复等一切

GitHub Flow工作流：

# 从主分支创建功能分支
git checkout main
git pull origin main
git checkout -b feature/add-search

# 提交更改
git commit -m "feat: 添加搜索组件"
git commit -m "test: 添加搜索测试"
git commit -m "docs: 文档化搜索API"

# 推送并创建拉取请求
git push -u origin feature/add-search

# 审查和CI通过后，通过PR合并
# 然后部署主分支

# 清理
git checkout main
git pull origin main
git branch -d feature/add-search

主干开发

最小化分支，短寿命功能分支：

# 主分支
main        # 主干，始终可部署

# 短寿命功能分支（<1天）
feature/*   # 小型、快速功能

主干开发工作流：

# 创建短寿命功能分支
git checkout main
git pull origin main
git checkout -b feature/update-button-text

# 进行专注更改
git commit -m "feat: 更新CTA按钮文本"

# 同一天推送并合并
git push -u origin feature/update-button-text

# 通过PR或直接合并
git checkout main
git merge feature/update-button-text
git push origin main

# 立即删除分支
git branch -d feature/update-button-text

GitLab Flow

部署阶段的环境分支：

# 主要开发分支
main              # 集成分支

# 环境分支
staging           # 暂存环境
production        # 生产环境

# 功能分支
feature/*         # 功能合并到main

GitLab Flow工作流：

# 开发功能
git checkout main
git checkout -b feature/notification-system
git commit -m "feat: 添加通知系统"

# 合并到main
git checkout main
git merge feature/notification-system

# 部署到暂存
git checkout staging
git merge main
git push origin staging  # 触发暂存部署

# 测试后，部署到生产
git checkout production
git merge staging
git push origin production  # 触发生产部署

代码示例

示例1：启动功能分支

# 更新主分支
git checkout main
git pull origin main

# 创建描述性功能分支
git checkout -b feature/456-implement-two-factor-auth

# 验证在新分支上
git branch --show-current
# 输出：feature/456-implement-two-factor-auth

# 进行初始提交
git commit --allow-empty -m "feat: 初始化双因素认证功能"

# 推送分支到远程
git push -u origin feature/456-implement-two-factor-auth

# 继续开发
git commit -m "feat: 添加TOTP令牌生成"
git commit -m "feat: 添加令牌验证端点"
git commit -m "test: 添加2FA集成测试"

示例2：保持功能分支更新

# 在功能分支工作时，主分支已前进
git checkout feature/789-user-dashboard

# 选项1：变基（创建线性历史）
git fetch origin
git rebase origin/main

# 如果发生冲突
git status  # 查看冲突文件
# 在编辑器中修复冲突
git add .
git rebase --continue

# 选项2：合并（保留分支历史）
git fetch origin
git merge origin/main

# 解决任何合并冲突
git add .
git commit -m "merge: 解决与主分支的冲突"

# 推送更新分支
git push --force-with-lease origin feature/789-user-dashboard

示例3：发布分支工作流

# 从开发分支创建发布分支
git checkout develop
git pull origin develop
git checkout -b release/v2.0.0

# 准备发布
git commit -m "chore: 版本升级到2.0.0"
git commit -m "docs: 为v2.0.0更新CHANGELOG"
git commit -m "chore: 更新依赖"

# 修复发布测试中发现的问题
git commit -m "fix: 解决用户验证边界情况"
git commit -m "fix: 修正API响应格式"

# 合并到主分支并标记
git checkout main
git merge --no-ff release/v2.0.0
git tag -a v2.0.0 -m "发布版本2.0.0

主要更改：
- 新用户认证系统
- 改进性能
- 更新API端点

详见CHANGELOG.md。"

# 合并回开发分支
git checkout develop
git merge --no-ff release/v2.0.0

# 推送所有内容
git push origin main
git push origin develop
git push origin v2.0.0

# 清理
git branch -d release/v2.0.0

示例4：紧急热修复

# 生产环境崩溃，需要立即修复
git checkout main
git pull origin main

# 创建热修复分支
git checkout -b hotfix/critical-login-bug

# 进行修复
git commit -m "fix: 解决登录处理程序空指针问题

用户邮箱字段包含尾随空格时无法登录。
添加trim()到邮箱输入处理。

关键生产问题影响15%登录尝试。"

# 测试修复
npm test

# 合并到主分支
git checkout main
git merge --no-ff hotfix/critical-login-bug
git tag -a v1.5.1 -m "热修复：登录问题修复"

# 立即部署
git push origin main
git push origin v1.5.1

# 合并到开发分支以防丢失
git checkout develop
git merge --no-ff hotfix/critical-login-bug
git push origin develop

# 清理
git branch -d hotfix/critical-login-bug
git push origin --delete hotfix/critical-login-bug

示例5：协作功能分支

# 开发者A启动功能
git checkout -b feature/payment-integration
git commit -m "feat: 添加支付网关客户端"
git push -u origin feature/payment-integration

# 开发者B加入工作
git fetch origin
git checkout feature/payment-integration

# 开发者B进行更改
git commit -m "feat: 添加Webhook处理程序"
git pull --rebase origin feature/payment-integration
git push origin feature/payment-integration

# 开发者A拉取更新
git checkout feature/payment-integration
git pull --rebase origin feature/payment-integration

# 继续协作直到完成
git commit -m "test: 添加支付集成测试"
git commit -m "docs: 文档化支付Webhook API"

# 创建拉取请求审查
git push origin feature/payment-integration

示例6：实验分支

# 尝试风险方法
git checkout -b experiment/new-architecture

# 进行实验提交
git commit -m "experiment: 尝试事件驱动架构"
git commit -m "experiment: 添加消息队列集成"

# 测试方法
npm test
npm run benchmark

# 决策1：实验失败，放弃
git checkout main
git branch -D experiment/new-architecture

# 决策2：实验成功，集成
git checkout -b feature/event-driven-refactor
git merge experiment/new-architecture
git commit -m "refactor: 迁移到事件驱动架构"
git push -u origin feature/event-driven-refactor

# 清理实验分支
git branch -d experiment/new-architecture

示例7：堆叠分支

# 大型功能需要多个PR
git checkout main

# 第一部分：数据库架构
git checkout -b feature/schema-updates
git commit -m "feat: 添加新数据库表"
git commit -m "feat: 添加迁移脚本"
git push -u origin feature/schema-updates

# 第二部分：API（依赖于架构）
git checkout -b feature/api-endpoints
git commit -m "feat: 添加用户API端点"
git commit -m "test: 添加API集成测试"
git push -u origin feature/api-endpoints

# 第三部分：UI（依赖于API）
git checkout -b feature/user-interface
git commit -m "feat: 添加用户管理UI"
git commit -m "test: 添加UI组件测试"
git push -u origin feature/user-interface

# 合并顺序：架构 -> API -> UI
# 每个PR批准合并后，将下一个分支变基到主分支

示例8：分支清理

# 列出所有分支
git branch -a

# 删除已合并的本地分支
git branch --merged main | grep -v "main" | xargs git branch -d

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

# 修剪远程跟踪分支
git fetch --prune

# 删除远程不再存在的本地分支
git remote prune origin

# 交互式清理
git branch -vv | grep ': gone]' | awk '{print $1}' | xargs git branch -D

# 查看陈旧分支
git for-each-ref --sort=-committerdate refs/heads/ \
  --format='%(committerdate:short) %(refname:short)'

何时使用此技能

在以下情况下使用此技能：

启动新项目并建立分支约定
规划跨多个开发者的功能开发
设置基于分支部署的CI/CD流水线
协调发布计划和版本管理
管理生产环境的热修复
新团队成员入职Git工作流
解决复杂合并情况
重构代码库大段内容
实验架构更改
同时维护软件多个版本

最佳实践

保持分支短寿命 - 在几天内合并，减少合并冲突
使用描述性分支名称 - 未来您会感谢现在
删除已合并分支 - 保持仓库清洁和可导航
每个分支一个目的 - 不混合功能、修复和重构
定期从主分支更新 - 频繁变基/合并减少冲突痛苦
保护主分支 - 要求PR审查、测试通过才合并
一致使用分支前缀 - 支持自动化和过滤
包含问题编号 - 创建需求可追溯性
尽早推送分支 - 启用协作并提供备份
尽早创建PR作为草稿 - 获取早期反馈
创建PR前审查更改 - 使用 git diff main...HEAD
编写有意义的合并提交 - 解释分支完成内容
标记发布 - 标记历史重要点
文档化分支策略 - 在README或CONTRIBUTING指南中
自动化分支清理 - 使用工具删除陈旧分支

常见陷阱

长寿命分支 - 几周老的分支合并噩梦
不一致命名 - 混合约定混淆所有人
直接在主分支工作 - 绕过审查和CI检查
分支前忘记拉取 - 从陈旧基部分支
从错误基部分支 - 功能从功能分支而不是主分支
不更新功能分支 - 与主分支偏离导致冲突
保留过多本地分支 - 杂乱了工作空间
强制推送共享分支 - 破坏合作者工作
混合无关更改 - 一个分支做太多事
不清理已合并分支 - 仓库变成坟场
创建嵌套分支层次 - 过度复杂的依赖
未经测试合并 - 破坏主分支
无分支保护规则 - 任何人都能推送到主分支
使用通用分支名称 - "修复"或"更新"不表达内容
忘记推送分支 - 工作仅本地存在

资源

Git命令用于分支管理

# 创建并切换到新分支
git checkout -b <分支名称>
git switch -c <分支名称>  # 现代替代

# 切换分支
git checkout <分支名称>
git switch <分支名称>     # 现代替代

# 列出分支
git branch              # 本地分支
git branch -r           # 远程分支
git branch -a           # 所有分支
git branch -vv          # 详细显示跟踪信息

# 删除分支
git branch -d <分支>          # 如果已合并则删除
git branch -D <分支>          # 强制删除
git push origin --delete <分支>  # 删除远程

# 重命名分支
git branch -m <旧> <新>       # 重命名本地
git push origin -u <新>        # 推送重命名
git push origin --delete <旧>  # 删除旧远程

# 跟踪远程分支
git branch -u origin/<分支>
git checkout --track origin/<分支>

# 比较分支
git diff main...功能分支
git log main..功能分支
git log --graph --oneline --all

# 合并策略
git merge <分支>              # 常规合并
git merge --no-ff <分支>      # 强制合并提交
git merge --squash <分支>     # 压缩为一个提交

# 变基
git rebase main                 # 变基到主分支
git rebase -i main              # 交互式变基
git rebase --continue           # 冲突后继续
git rebase --abort              # 放弃变基

# 拣选
git cherry-pick <提交哈希>   # 应用特定提交

分支保护规则

在GitHub/GitLab配置：

保护分支：main
- 要求拉取请求审查：2名审查者
- 要求状态检查通过：true
  - 测试
  - 代码风格检查
  - 构建
- 要求分支最新：true
- 包括管理员：true
- 限制推送：true
- 允许强制推送：false
- 允许删除：false

Git别名用于分支管理

添加到.gitconfig：

[别名]
    # 分支管理
    br = branch
    co = checkout
    cob = checkout -b

    # 分支清理
    bclean = "!f() { git branch --merged ${1-main} | grep -v " ${1-main}$" | xargs git branch -d; }; f"

    # 分支状态
    bstat = branch -vv

    # 最近分支
    recent = branch --sort=-committerdate --format='%(committerdate:short) %(refname:short)'

    # 当前分支名称
    current = branch --show-current

    # 推送当前分支
    pub = "!git push -u origin $(git current)"

    # 从主分支更新
    update = "!git fetch origin && git rebase origin/main"

可视化工具

# 查看分支结构
git log --graph --oneline --all --decorate

# 详细分支图
git log --graph --pretty=format:'%Cred%h%Creset -%C(yellow)%d%Creset %s %Cgreen(%cr) %C(bold blue)<%an>%Creset' --abbrev-commit --all

# 查看所有分支及最后提交
git branch -v

# 分支拓扑
git show-branch

# 可视化Git工具
gitk --all          # 内置可视化器
git gui             # 内置GUI

高级模式

功能标志用于主干开发

代替长寿命分支，使用功能标志：

// feature-flags.js
export const features = {
  newUserDashboard: process.env.ENABLE_NEW_DASHBOARD === 'true',
  betaPaymentFlow: process.env.ENABLE_BETA_PAYMENT === 'true',
};

// component.jsx
import { features } from './feature-flags';

function Dashboard() {
  if (features.newUserDashboard) {
    return <NewDashboard />;
  }
  return <LegacyDashboard />;
}

这允许合并不完整功能到主分支而不暴露它们：

# 提交部分功能到主分支
git checkout main
git commit -m "feat: 添加新仪表板（通过功能标志隐藏）"
git push origin main

# 功能已部署但不活跃
# 准备就绪后通过环境变量启用

分支策略文档化

在CONTRIBUTING.md中记录：

## 分支策略

我们使用GitHub Flow，遵循以下约定：

### 分支类型

- `feature/*` - 新功能
- `fix/*` - 错误修复
- `hotfix/*` - 生产环境紧急修复
- `refactor/*` - 代码改进
- `docs/*` - 文档

### 工作流

1. 从`main`创建分支：`git checkout -b feature/123-description`
2. 遵循我们的提交消息指南进行提交
3. 保持分支更新：`git rebase origin/main`
4. 推送并创建PR：`git push -u origin feature/123-description`
5. 批准和CI通过后，通过PR合并
6. 合并后删除分支

### 分支命名

格式：`<类型>/<问题>-<描述>`

示例：
- `feature/456-user-authentication`
- `fix/789-memory-leak`
- `hotfix/101-critical-security-patch`

### 分支生命周期

- 从最新`main`创建分支
- 保持分支不超过3天
- 合并后立即删除
- 从不强制推送到`main`

结论

有效的分支策略对于讲述清晰的开发故事至关重要。通过遵循一致的命名约定、保持分支专注和短寿命，并选择适合团队需求的分支模型，您可以创建一个可导航、可理解且有价值的Git历史。

记住：分支是专注开发的临时工作空间。使用它们来隔离更改、支持并行工作和便于代码审查。然后合并并清理它们。干净的分支结构是健康、管理良好的代码库的标志。

Git故事讲述-分支策略Skill git-storytelling-branch-strategy