git-workflow-designer

Git 工作流设计技能

概述

此技能可帮助你为任何规模的团队设计并实施有效的 Git 分支策略。涵盖 Git Flow、GitHub Flow、基于主干的开发、发布管理和分支保护策略。

工作流选择理念

关键因素

1. 团队规模：个人 vs. 小型团队 vs. 大型组织
2. 发布频率：持续发布 vs. 定期发布
3. 环境复杂度：单个 vs. 多个部署目标
4. 风险承受能力：快速推进 vs. 稳定优先

工作流对比

工作流	最适用于	发布频率	复杂度
基于主干	小型团队、CI/CD	持续	低
GitHub Flow	大多数 Web 应用	按需	低
Git Flow	有版本管理的软件	定期	高
GitLab Flow	基于环境的工作流	混合	中

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

概述

适用于持续部署的简单、高效工作流。

main ─────●─────●─────●─────●─────●─────●
            \       /   \       /
feature/x    ●─────●     ●─────●

流程

1. 从 main 创建分支

   git checkout main
   git pull origin main
   git checkout -b feature/user-authentication
   

2. 定期提交

   git add .
   git commit -m "feat: add login form component"
   

3. 推送并创建 PR

   git push -u origin feature/user-authentication
   gh pr create --title "Add user authentication" --body "..."
   

4. 审查并合并

   • CI 运行测试
   • 同行审查
   • Squash 合并到 main

5. 部署

   • 合并到 main 后自动部署

分支命名约定

feature/  - New features
fix/      - Bug fixes
docs/     - Documentation
refactor/ - Code refactoring
test/     - Test additions
chore/    - Maintenance tasks

配置

# .github/branch-protection.yml (pseudo-config)
main:
  required_status_checks:
    strict: true
    contexts:
      - "ci/tests"
      - "ci/lint"
      - "ci/build"
  required_pull_request_reviews:
    required_approving_review_count: 1
    dismiss_stale_reviews: true
  enforce_admins: false
  restrictions: null

Git Flow（适用于有版本管理的发布）

概述

适用于定期发布周期的结构化工作流。

main     ─────●─────────────────●─────────────●
               \               /               \
release         ●─────●─────●─                  ●───
                 \     \   /                   /
develop   ●─────●─●─────●─●─────●─────●─────●─●
            \   /   \       /     \       /
feature      ●─●     ●─────●       ●─────●

分支

分支	用途	合并到
main	可用于生产环境的代码	-
develop	集成分支	main
feature/*	新功能	develop
release/*	发布准备	main、develop
hotfix/*	紧急修复	main、develop

功能开发

# Start feature
git checkout develop
git pull origin develop
git checkout -b feature/new-dashboard

# Work on feature
git commit -m "feat: add dashboard layout"
git commit -m "feat: add dashboard charts"

# Complete feature
git checkout develop
git merge --no-ff feature/new-dashboard
git branch -d feature/new-dashboard
git push origin develop

发布流程

# Start release
git checkout develop
git checkout -b release/1.2.0

# Bump version
npm version 1.2.0 --no-git-tag-version
git commit -am "chore: bump version to 1.2.0"

# Fix release issues
git commit -m "fix: correct typo in release notes"

# Complete release
git checkout main
git merge --no-ff release/1.2.0
git tag -a v1.2.0 -m "Release 1.2.0"
git push origin main --tags

git checkout develop
git merge --no-ff release/1.2.0
git push origin develop

git branch -d release/1.2.0

热修复流程

# Start hotfix
git checkout main
git checkout -b hotfix/1.2.1

# Fix the issue
git commit -m "fix: critical security vulnerability"

# Complete hotfix
git checkout main
git merge --no-ff hotfix/1.2.1
git tag -a v1.2.1 -m "Hotfix 1.2.1"
git push origin main --tags

git checkout develop
git merge --no-ff hotfix/1.2.1
git push origin develop

git branch -d hotfix/1.2.1

基于主干的开发

概述

所有人都向 main 提交代码，并使用短期分支。

main ─●─●─●─●─●─●─●─●─●─●─●─●─●─●─●─●
        \─/   \─/       \─/
        PR    PR        PR

原则

1. 短期分支（< 1 天）
2. 小步、频繁提交
3. 使用功能标志管理未完成的工作
4. 完善的 CI/CD

功能标志集成

// src/lib/features.ts
export const features = {
  newCheckout: process.env.FEATURE_NEW_CHECKOUT === 'true',
  darkMode: process.env.FEATURE_DARK_MODE === 'true',
};

// Usage
if (features.newCheckout) {
  return <NewCheckout />;
}
return <OldCheckout />;

分支规则

# Quick feature (< 4 hours)
git checkout main
git pull
git checkout -b quick/fix-typo
# ... work ...
git push -u origin quick/fix-typo
gh pr create --title "Fix typo" --body ""
# Merge immediately after CI passes

发布管理

语义化版本

MAJOR.MINOR.PATCH

1.0.0 - Initial release
1.1.0 - New feature (backwards compatible)
1.1.1 - Bug fix
2.0.0 - Breaking change

自动递增版本号

// package.json
{
  "scripts": {
    "release:patch": "npm version patch && git push --follow-tags",
    "release:minor": "npm version minor && git push --follow-tags",
    "release:major": "npm version major && git push --follow-tags"
  }
}

生成变更日志

# .github/workflows/release.yml
name: Release

on:
  push:
    tags:
      - 'v*'

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Generate changelog
        id: changelog
        uses: metcalfc/changelog-generator@v4
        with:
          myToken: ${{ secrets.GITHUB_TOKEN }}

      - name: Create Release
        uses: actions/create-release@v1
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        with:
          tag_name: ${{ github.ref }}
          release_name: Release ${{ github.ref }}
          body: ${{ steps.changelog.outputs.changelog }}

约定式提交

# Format
<type>(<scope>): <description>

[optional body]

[optional footer(s)]

# Types
feat:     New feature
fix:      Bug fix
docs:     Documentation
style:    Formatting, no code change
refactor: Refactoring
test:     Tests
chore:    Maintenance

# Examples
feat(auth): add password reset flow
fix(api): handle null user gracefully
docs: update README with new API endpoints
chore(deps): update dependencies

Commitlint 配置

// commitlint.config.js
module.exports = {
  extends: ['@commitlint/config-conventional'],
  rules: {
    'type-enum': [
      2,
      'always',
      [
        'feat',
        'fix',
        'docs',
        'style',
        'refactor',
        'test',
        'chore',
        'perf',
        'ci',
        'build',
        'revert',
      ],
    ],
    'subject-case': [2, 'always', 'lower-case'],
    'header-max-length': [2, 'always', 72],
  },
};

分支保护

GitHub 分支保护规则

# Recommended settings for main branch

Required status checks:
  - ci/test
  - ci/lint
  - ci/build
  - ci/typecheck

Required reviews: 1
Dismiss stale reviews: true
Require review from code owners: true

Require signed commits: false  # Optional
Require linear history: true   # Encourages squash/rebase

Include administrators: false  # Allow admins to bypass

Restrict who can push:
  - Maintainers only

CODEOWNERS

# .github/CODEOWNERS

# Default owners
* @team-lead

# Frontend
/src/components/ @frontend-team
/src/app/ @frontend-team

# Backend
/src/api/ @backend-team
/src/lib/db/ @backend-team

# Infrastructure
/.github/ @devops-team
/docker/ @devops-team

# Docs
/docs/ @tech-writer
*.md @tech-writer

合并策略

Squash 并合并（推荐）

# Clean history, one commit per feature
git merge --squash feature/branch
git commit -m "feat: complete feature description"

优点：

• main 历史记录简洁
• 便于还原功能
• 可以编辑提交消息

缺点：

• 丢失各个提交的历史记录

Rebase 并合并

# Linear history, preserves commits
git rebase main feature/branch
git checkout main
git merge feature/branch

优点：

• 线性历史记录
• 保留各个提交
• 便于使用 bisect

缺点：

• 需要整洁的提交
• 可能需要强制推送

合并提交

# Preserves full history with merge points
git merge --no-ff feature/branch

优点：

• 保留完整历史记录
• 合并点清晰
• 无需强制推送

缺点：

• 历史记录杂乱
• 更难浏览

常见场景

将功能分支与 Main 同步

# Option 1: Rebase (clean history)
git checkout feature/my-feature
git fetch origin
git rebase origin/main
git push --force-with-lease

# Option 2: Merge (safe, but noisy)
git checkout feature/my-feature
git merge origin/main
git push

撤销上一次提交（尚未推送）

# Keep changes staged
git reset --soft HEAD~1

# Keep changes unstaged
git reset HEAD~1

# Discard changes
git reset --hard HEAD~1

修复提交消息

# Last commit only
git commit --amend -m "new message"

# Older commits (interactive rebase)
git rebase -i HEAD~3
# Change 'pick' to 'reword' for target commit

Cherry-pick 特定提交

# Apply specific commit to current branch
git cherry-pick abc123

# Cherry-pick without committing
git cherry-pick --no-commit abc123

恢复已删除的分支

# Find the commit
git reflog

# Recreate branch
git checkout -b recovered-branch abc123

工作流脚本

Git 别名

# ~/.gitconfig
[alias]
    # Status
    s = status -sb

    # Branching
    co = checkout
    cob = checkout -b
    br = branch -vv

    # Commits
    cm = commit -m
    ca = commit --amend --no-edit

    # Logging
    lg = log --oneline --graph --decorate -20
    lga = log --oneline --graph --decorate --all -20

    # Sync
    sync = !git fetch origin && git rebase origin/main

    # Cleanup
    cleanup = !git branch --merged | grep -v main | xargs git branch -d

    # Undo
    undo = reset --soft HEAD~1

功能分支脚本

#!/bin/bash
# scripts/feature.sh

set -e

BRANCH_TYPE=${1:-feature}
BRANCH_NAME=$2

if [ -z "$BRANCH_NAME" ]; then
    echo "Usage: ./scripts/feature.sh [type] <name>"
    echo "Types: feature, fix, docs, chore"
    exit 1
fi

FULL_BRANCH="$BRANCH_TYPE/$BRANCH_NAME"

echo "Creating branch: $FULL_BRANCH"

git checkout main
git pull origin main
git checkout -b "$FULL_BRANCH"

echo "Branch '$FULL_BRANCH' created and checked out"
echo "Run: git push -u origin $FULL_BRANCH"

工作流检查清单

选择工作流前

• 了解团队规模和分布情况
• 明确发布频率
• 评估 CI/CD 成熟度
• 考虑部署环境

实施

• 在 CONTRIBUTING.md 中记录工作流
• 配置分支保护规则
• 设置 CODEOWNERS
• 配置合并策略
• 添加提交消息检查
• 创建 Git 别名/脚本

维护

• 定期清理分支
• 监控合并队列
• 审查并更新保护规则
• 培训新团队成员

何时使用此技能

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

• 启动新项目并选择工作流
• 从个人开发扩展到团队开发
• 改进发布管理
• 设置分支保护规则
• 制定贡献指南
• 解决 Git 工作流冲突
• 实施约定式提交