managing-git-workflows

Git 工作流

实现结构化的 Git 工作流，以支持团队协作、代码质量保障和自动发布。本技能涵盖分支策略、Conventional Commits 格式、Git hooks 和 monorepo 管理模式。

何时使用此技能

在以下情况使用此技能：

• 为新项目或团队选择分支策略
• 统一提交消息格式
• 设置用于 lint、测试或验证的 Git hooks
• 管理包含多个项目的 monorepo
• 建立代码评审工作流
• 自动执行版本管理和发布

快速决策：选择哪种分支策略？

Trunk-Based Development

适用于团队拥有完善的 CI/CD 自动化、全面的测试覆盖率（80% 以上），并且频繁部署（每天或更频繁）的情况。短期分支应在 1 天内合并。未完成的功能需要使用功能开关。

最适合： DevOps 实践成熟、开发速度快的团队（Google、Facebook、Netflix）

GitHub Flow

适用于持续部署的 Web 应用。主分支始终代表生产环境。适合小型到中型团队（2-20 名开发者）的简单 PR 工作流。

最适合： 初创公司、SaaS 产品、开源项目

GitFlow

适用于需要同时支持多个生产版本、要求正式 QA 周期或遵循定期发布（每月、每季度）的情况。流程更复杂，但结构清晰。

最适合： 企业软件、通过 App Store 发布的移动应用、本地部署产品

如需查看包含示例的详细分支模式，请参阅 references/branching-strategies.md。

Conventional Commits

按照结构编写提交消息，以便自动管理版本和生成变更日志：

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

常见类型：

• feat - 新功能（MINOR 版本递增：0.1.0）
• fix - 错误修复（PATCH 版本递增：0.0.1）
• docs - 仅涉及文档
• refactor - 重构代码，但不更改功能
• test - 添加或更新测试
• chore - 维护任务

破坏性变更：

• 在类型后添加 !：feat!: 或 fix!:
• 在页脚添加 BREAKING CHANGE:
• 将导致 MAJOR 版本递增（1.0.0）

示例：

git commit -m "feat(auth): add JWT token validation"
git commit -m "fix: resolve race condition in user login"
git commit -m "feat!: redesign authentication API

BREAKING CHANGE: Auth endpoints now require API version header"

如需查看完整规范和工具配置，请参阅 references/conventional-commits.md。

用于质量门禁的 Git Hooks

在工作流的关键环节自动执行代码质量检查：

pre-commit - 在创建提交前运行

• Lint 检查（ESLint、Prettier）
• 格式检查
• 快速测试

commit-msg - 验证提交消息格式

• 强制使用 Conventional Commits
• 检查消息长度

pre-push - 推送到远程仓库前运行

• 完整测试套件
• 防止向受保护分支强制推送

使用 Husky 快速设置：

npm install --save-dev husky lint-staged @commitlint/cli @commitlint/config-conventional
npx husky init
npx husky add .husky/pre-commit "npx lint-staged"
npx husky add .husky/commit-msg 'npx --no -- commitlint --edit $1'

如需查看完整的 hook 配置和示例，请参阅 references/git-hooks-guide.md。

Monorepo 管理

构建工具选择

Nx - 最适合 TypeScript/JavaScript monorepo

• 依赖关系图分析
• 受影响项目命令（仅重新构建有变更的项目）
• 分布式缓存

Turborepo - 最适合 Next.js/React 应用

• 快速增量构建
• 远程缓存
• 配置简单

稀疏检出 - 适用于无需完整克隆的大型仓库

git sparse-checkout init --cone
git sparse-checkout set apps/web libs/ui-components

代码所有权

使用 .github/CODEOWNERS 定义代码所有权：

# Default owners
* @org/engineering

# Apps ownership
/apps/web/ @org/web-team
/apps/mobile/ @org/mobile-team

# Security-critical
/libs/auth/ @org/security-team @org/principal-engineers

如需查看详细的 monorepo 模式，请参阅 references/monorepo-patterns.md。

合并还是变基

合并提交

需要保留完整历史记录时使用：

git checkout main
git merge feature-branch

适用情况： 功能分支有多位开发者参与，且希望查看合并节点

压缩并合并

需要保持历史记录整洁、线性时使用：

git checkout main
git merge --squash feature-branch
git commit -m "feat: add user authentication"

适用情况： 功能分支包含大量 WIP 提交，且希望主分支历史记录保持整洁

变基

需要保持历史记录线性且不包含合并提交时使用：

git checkout feature-branch
git rebase main

适用情况： 更新功能分支、独立开发或在创建 PR 前整理提交

⚠️ 切勿对以下内容进行变基： 公共分支（main、develop），或已推送并被他人使用的提交

代码评审工作流

Pull Request 模板

创建 .github/PULL_REQUEST_TEMPLATE.md：

## Description


## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update

## Checklist
- [ ] Code follows style guidelines
- [ ] Self-reviewed code
- [ ] Added tests
- [ ] Updated documentation
- [ ] Tests pass locally

分支保护规则

通过仓库设置强制执行质量门禁：

• 要求拉取请求评审（至少 2 个批准）
• 要求通过状态检查（构建、测试、代码检查）
• 合并前要求分支保持最新
• 限制强制推送和删除

完整的代码评审设置说明，请参阅 references/code-review-workflows.md。

分支命名约定

使用一致的命名方式，保持清晰：

• feature/user-authentication - 新功能
• bugfix/login-error - 缺陷修复
• hotfix/critical-security-issue - 紧急生产环境修复
• docs/api-documentation - 文档变更
• refactor/database-layer - 代码重构

使用 Git 钩子验证分支名称（参见 scripts/check-branch-name.sh）。

高级技巧

为热修复挑选提交

将特定提交应用到其他分支：

git checkout main
git commit -m "fix: resolve critical security issue"
# Commit hash: a1b2c3d

git checkout release/1.5
git cherry-pick a1b2c3d

使用 Git LFS 管理大文件

将大文件与代码分开跟踪：

git lfs install
git lfs track "*.psd"
git lfs track "*.mp4"
git add .gitattributes

发布版本打标签

标记生产版本：

git tag -a v1.2.0 -m "Release version 1.2.0"
git push origin v1.2.0

交互式变基

在 PR 前清理提交历史：

git rebase -i HEAD~3
# Squash WIP commits, reword messages, reorder commits

详细示例请参阅 examples/ 目录。

自动化发布工作流

结合约定式提交与 CI/CD，实现自动版本管理：

1. 提交 - 遵循约定格式
2. 分析 - Semantic Release 分析提交类型
3. 版本 - 确定 MAJOR.MINOR.PATCH 版本变更
4. 更新日志 - 根据提交自动生成
5. 打标签 - 创建 Git 标签
6. 发布 - 部署到 npm、GitHub 发布等

完整配置请参阅 examples/semantic-release-setup/。

工具推荐

Git 钩子：

• Husky - 简化钩子管理（最受欢迎）
• lint-staged - 仅对暂存文件运行代码检查工具（提升性能）

提交验证：

• Commitlint - 强制使用约定式提交
• Semantic Release - 自动版本管理

单体仓库构建：

• Nx - TypeScript/JavaScript（Google、AWS 都在使用）
• Turborepo - Next.js/React（Vercel）

大文件：

• Git LFS - 存储大型二进制文件

所有工具均通过 Context7 验证，信任评分较高（2025 年 12 月）。

与其他技能集成

building-ci-pipelines - Git 工作流会触发 CI/CD 流水线，分支保护会强制执行 CI 检查

writing-github-actions - GitHub Actions 可自动执行工作流步骤（发布、PR 检查）

infrastructure-as-code - IaC 仓库需要结构化工作流，GitOps 使用 Git 作为事实来源

testing-strategies - Git 钩子强制执行测试要求，推送前运行测试套件

security-hardening - Git 钩子可防止提交密钥，签名提交可验证身份，CODEOWNERS 可强制执行安全评审

快速参考

主干开发工作流

git checkout -b feature/add-login main
git add .
git commit -m "feat: add login form component"
git rebase origin/main  # Stay up to date
git push origin feature/add-login
# PR → merge → delete branch (within 24 hours)

GitHub Flow 工作流

git checkout -b feature/user-auth main
git commit -m "feat: add JWT authentication"
git commit -m "test: add auth tests"
git push origin feature/user-auth
# Open PR → review → merge → deploy → delete branch

GitFlow 工作流

# Feature
git checkout -b feature/user-profile develop
git commit -m "feat: add user profile"
git checkout develop
git merge --no-ff feature/user-profile

# Release
git checkout -b release/1.1.0 develop
git checkout main
git merge --no-ff release/1.1.0
git tag -a v1.1.0 -m "Release 1.1.0"

# Hotfix
git checkout -b hotfix/critical-bug main
git checkout main
git merge --no-ff hotfix/critical-bug
git tag -a v1.1.1 -m "Hotfix 1.1.1"

验证脚本

运行自动化检查：

• scripts/validate-commit-msg.sh - 验证提交消息格式
• scripts/check-branch-name.sh - 验证分支命名约定
• scripts/setup-hooks.sh - 自动安装钩子

直接执行脚本（无需令牌）进行验证。