git-workflow

Git 工作流（现代团队协作）

采用现代 Git 协作模式：持续部署使用 GitHub Flow，大规模团队使用主干开发，自动化使用 Conventional Commits，大型功能使用堆叠式差异。

使用此技能选择分支模型、规范 PR 流程、执行提交约定，并强化仓库设置以确保安全协作。

快速入门

1. 明确约束（团队规模、发布节奏、CI 成熟度、合规要求）。
2. 使用决策树选择分支策略。
3. 应用仓库基线设置（分支保护、审批、检查、合并策略）。
4. 查阅相关参考文档，了解实现细节。
5. 如果有人询问“2026 年的最佳实践”，请通过网页搜索进行核实，并以 data/sources.json 作为起始来源列表。

快速参考

任务	工具/命令	使用时机	参考资料
创建功能分支	git switch -c feat/name main	开始新工作	分支策略
创建功能工作树	git worktree add ../wt-feature -b feature/name origin/dev	为每个分支隔离一个功能	分支策略
压缩 WIP 提交	git rebase -i HEAD~3	PR 前整理提交	交互式变基
Conventional commit	git commit -m "feat: add feature"	所有提交	提交约定
安全地强制推送	git push --force-with-lease	变基后	常见错误
解决冲突	git mergetool	合并冲突时	冲突解决
创建堆叠式 PR	gt create stack-name (Graphite)	大型功能	堆叠式差异
自动生成变更日志	npx standard-version	发布前	发布管理
运行质量门禁	GitHub Actions / GitLab CI	每个 PR	自动化质量门禁

AI Agent 功能循环

对于 AI 辅助工程，建议采用以下默认循环：

1. 为每个功能分支创建一个工作树。
2. 仅实现该功能范围内的更改。
3. 在创建 PR 前运行仓库质量门禁。
4. 向集成分支创建一个聚焦的 PR。

如果仓库中有脚本（例如 scripts/git/feature-workflow.sh），请使用它们来规范此循环。

本地安全预检（检出/合并/提交前）

使用以下快速步骤，避免 Agent 驱动的工作中遇到常见的本地 Git 阻碍。

1. 检查工作树是否干净：

• git status --porcelain
• 如果输出非空，请明确决定：提交、暂存或中止分支切换。

2. 检查锁文件/进程：

• 如果 Git 命令因 index.lock 而失败，请先检查正在运行的 Git 进程：
  • test -f .git/index.lock && ps aux | rg "[g]it"
• 确认没有活动的 Git 进程后，才移除过期锁文件。

3. 分支切换检查：

• 如果本地更改会被覆盖，请勿执行 checkout/switch。
• 有意地提交或暂存；避免意外丢失上下文。

4. 合并冲突处理流程：

• 遇到冲突时，停止新增编辑，逐个文件解决冲突，重新运行相关测试，然后完成合并提交。

5. 自动化说明：

• 对于重复的分支操作，优先使用项目脚本/工作树，而不是临时手动切换本地分支。

决策树：选择分支策略

Use this decision tree to select the optimal branching strategy for your team based on team size, release cadence, and CI/CD maturity.

Team characteristics -> What's your situation?
    ├─ Small team (1-5 devs) + Continuous deployment + High CI/CD maturity?
    │   └─ GitHub Flow (main + feature branches)
    │
    ├─ Medium team (5-15 devs) + Continuous deployment + High CI/CD maturity?
    │   └─ Trunk-Based Development (main + short-lived branches)
    │
    ├─ Large team (15+ devs) + Continuous deployment + Very high CI/CD maturity?
    │   └─ Trunk-Based + Feature Flags (progressive rollout)
    │
    ├─ Scheduled releases + Medium CI/CD maturity?
    │   └─ GitFlow (main + develop + release branches)
    │
    └─ Multiple versions + Low-Medium CI/CD maturity?
        └─ GitFlow (long-lived release branches)

导航：核心工作流

分支策略

分支策略对比 - 选择和实施分支策略的综合指南

• GitHub Flow（推荐现代团队使用）：简单，支持持续部署
• Trunk-Based Development（适用于企业规模）：短生命周期分支，每日合并
• GitFlow（结构化发布）：定期发布，支持多个版本
• 决策矩阵：团队规模、发布节奏、CI/CD 成熟度
• 不同策略之间的迁移路径

Pull Request 最佳实践

PR 最佳实践指南 - 高效代码审查与快速 PR 周期

• PR 大小指南：让 PR 易于审查（通常 200-400 LOC 效果不错；更大的改动应拆分）
• 审查类别：BLOCKER、WARNING、NITPICK
• 审查礼仪：协作式反馈、代码示例
• PR 描述模板：内容、原因、方式、测试
• 基于数据的审查效率洞察

提交规范

Conventional Commits 标准 - 提交消息格式与语义化版本集成

• Conventional commit 格式：type(scope): description
• 提交类型：feat、fix、BREAKING CHANGE、refactor、docs
• SemVer 自动化：根据提交自动提升版本号
• 变更日志生成：根据提交历史自动生成
• 工具：commitlint、semantic-release、standard-version

---

导航：高级技术

堆叠差异

堆叠差异实现 - 特定平台的工作流与团队采用指南

• 什么是堆叠差异：将大型功能拆分为便于审查的小块
• 适用场景：超过 500 行的功能、复杂重构
• GitLab 原生支持：MR 链
• 使用 Graphite 的 GitHub：基于 CLI 的堆叠
• 优势：审查周期快 60%，质量更高

交互式变基

交互式变基与历史清理 - 保持提交历史整洁

• 自动压缩工作流：fixup! 和 squash! 提交
• 交互式变基命令：pick、reword、edit、squash、fixup、drop
• 拆分提交：将大型提交拆分为聚焦的改动
• 重新排序提交：构建逻辑清晰的提交历史
• 最佳实践：切勿对公共分支进行变基

冲突解决

冲突解决技巧 - 合并策略与冲突处理

• 解决策略：--ours、--theirs、手动合并
• 变基与合并：何时使用各自的方式
• 合并工具设置：VS Code、Meld、自定义工具
• 冲突标记：了解 <<<<<<<、=======、>>>>>>>
• 预防策略：频繁变基、小型 PR

---

导航：自动化与质量

自动化质量门禁

自动化质量门禁 - CI/CD 流水线与质量保障

• 必要门禁：测试、覆盖率、Lint、安全扫描
• 高级门禁：性能基准测试、包体积、a11y 检查
• GitHub Actions 工作流：完整的 PR 检查流水线
• GitLab CI 流水线：MR 质量门禁
• 提交前钩子：Husky + lint-staged 设置
• 质量指标阈值：覆盖率 80%，复杂度 < 10

验证检查清单

验证检查清单 - PR 前、合并前、发布前检查清单

• 创建 PR 前：代码质量、提交规范、测试
• 合并 PR 前：审查流程、CI/CD 检查、最终验证
• 发布前：发布前测试、版本管理、文档
• 部署后：立即验证、监控、任务
• 热修复检查清单：严重 Bug 快速处理流程

发布管理

发布管理 - 版本控制与部署工作流

• 语义化版本：MAJOR.MINOR.PATCH
• 手动发布工作流：GitFlow 发布分支
• 自动发布：semantic-release 自动化
• 热修复工作流：紧急补丁
• 变更日志生成：Keep a Changelog 格式
• 发布检查清单：发布前、发布当天、发布后

---

导航：学习与故障排除

单体仓库工作流

单体仓库工作流 - 单体仓库的 Git 模式

• 单体仓库的主干开发分支策略
• 稀疏检出和部分克隆
• 仅构建受影响部分的 CI（Nx、Turborepo、Bazel）
• 为每个软件包/目录设置 CODEOWNERS
• 单体仓库与多仓库决策表

Git 钩子自动化

Git 钩子自动化 - Pre-commit、commit-msg、pre-push 钩子

• Husky v9+ 和 lefthook 设置
• 集成 lint-staged 和 commitlint
• 自定义钩子（gitleaks、文件大小限制、分支命名）
• 团队分发策略

Git Bisect 调试

Git Bisect 调试 - 使用 git bisect 排查回归问题

• 手动和自动化 bisect 工作流
• 编写 bisect 测试脚本
• 处理合并提交、日志和重放

常见错误

常见错误与修复方法 - 从常见问题中汲取经验

• 大型且缺乏重点的 PR -> 拆分为堆叠差异
• 含糊的提交消息 -> 使用约定式提交
• 重写公开历史 -> 绝不对 main 执行 rebase
• 忽略审查意见 -> 处理所有反馈
• 提交密钥 -> 使用环境变量
• 强制推送的风险 -> 使用 --force-with-lease

决策表

何时使用各种分支策略

要求	GitHub Flow	Trunk-Based	GitFlow
持续部署	[OK] 最佳	[OK] 最佳	[FAIL] 较差
定期发布	[WARNING] 尚可	[WARNING] 尚可	[OK] 最佳
多个版本	[FAIL] 较差	[FAIL] 较差	[OK] 最佳
小型团队（< 5 人）	[OK] 最佳	[WARNING] 尚可	[FAIL] 过度设计
大型团队（> 15 人）	[WARNING] 尚可	[OK] 最佳	[WARNING] 尚可
快速迭代	[OK] 最佳	[OK] 最佳	[FAIL] 较差

PR 大小与审查时间

LOC	审查时间	Bug 检测率	建议
< 50	< 10 分钟	高	[OK] 非常适合热修复
50-200	10-30 分钟	高	[OK] 非常适合功能开发
200-400	30-60 分钟	中高	[OK] 可以接受
400-1000	1-2 小时	中	[WARNING] 考虑拆分
> 1000	> 2 小时	低	[FAIL] 始终拆分

应做 / 避免

好：应做

• 将 PR 控制在 400 行以内（200-400 行最佳）
• 使用约定式提交消息
• 打开 PR 前执行 rebase（保持历史整洁）
• 合并前至少要求一人批准
• 对每个 PR 运行 CI 检查
• 大型功能（>500 LOC）使用堆叠差异
• 合并前压缩 WIP 提交
• 使用 --force-with-lease（而非 --force）

不好：避免

• 长期存在的功能分支（>3 天）
• 未经审查就合并
• 对公开/共享分支执行 rebase
• 强制推送到 main/master
• 提交密钥（即使是“临时”提交）
• 大型单体 PR（>1000 行）
• 含糊的提交消息（“fix”“update”）
• 为了更快合并而跳过 CI

反模式

反模式	问题	修复方法
长期存在的分支	合并冲突、代码过时	主干开发、短期分支
未经审查的合并	Bug 流入生产环境	分支保护规则
对 main 执行 rebase	历史记录损坏	绝不对公开分支执行 rebase
1000+ LOC 的 PR	审查质量差	堆叠差异、拆分 PR
“fix”提交	历史记录含糊不清	约定式提交
没有 CI 门禁	main 被破坏	必需的状态检查
历史记录中包含密钥	安全漏洞	Pre-commit 钩子、gitleaks

仓库基线（安全性 + 可靠性）

在扩大团队规模前，先设置这些仓库默认项：

• 分支保护：要求通过 PR 合并到 main（禁止直接推送），要求通过状态检查，并要求合并时分支保持最新。
• 审查门槛：要求获得批准；对敏感路径（身份验证、支付、基础设施、生产配置）强制执行 CODEOWNERS。
• 历史记录策略：选择合并策略（压缩提交或合并提交）并保持一致；记录例外情况。
• 签名变更：要求为提交和发布标签签名（由团队自行管理密钥）。
• 防止泄露机密：使用本地 pre-commit 和服务器端机密扫描/推送保护；发生事件时轮换密钥。
• 安全合并：繁忙的仓库使用合并队列（或等效机制），确保高并发下 main 保持绿色。
• 成本控制：缓存依赖项和构建产物；按条件运行繁重任务；限制不受信任的 fork 可使用的 CI 分钟数。

模板：assets/pull-requests/pr-template.md
指南：assets/template-git-workflow-guide.md

安全敏感变更

有关安全相关的 git 操作，请参阅 git-commit-message/assets/template-security-commits.md：

• 使用 pre-commit 钩子检测机密
• 处理意外提交的机密
• 安全提交元数据（CVE、CVSS）
• 保护安全敏感代码的分支

可选：AI/自动化

注意：AI 工具可以提供帮助，但不能取代人类对合并决策的判断。

• PR 摘要 - 根据提交生成描述
• 变更风险标记 - 标记高风险文件（身份验证、支付）
• 审查建议 - 找出潜在审查者

有限声明

• AI 摘要需要人工核验
• 风险标记仅供参考，不作保证
• 合并决策始终需要人工批准

---

相关技能

• 软件代码审查 - 代码审查标准和技巧
• 质量调试 - Git bisect、调试工作流
• DevOps 平台工程 - CI/CD 流水线、自动化
• 软件测试与自动化 - 测试驱动开发、覆盖率门槛
• 文档规范 - 更新日志格式、文档工作流
• Git 提交消息 - 提交消息规范、安全提交

使用说明

适用于 Claude Code：

• 对大多数现代团队，建议使用 GitHub Flow（简单、有效）
• 对超过 500 行的功能，建议使用堆叠式差异
• 始终根据 Conventional Commits 格式验证提交消息
• 检查 PR 大小 - 超过 400 行时警告，超过 1000 行时阻止
• 参考 assets/ 获取可直接复制粘贴的配置
• 使用 references/ 获取深入的实现指南

渐进式披露：

1. 从快速参考开始，以便快速查找
2. 使用决策树选择策略
3. 前往具体资源查看详细实现
4. 参考模板获取可用于生产环境的配置
5. 在 PR/合并/发布前查看验证清单

---

快速命令参考

常见操作：

# Rebase feature branch
git fetch origin && git rebase origin/main

# Interactive rebase last 3 commits
git rebase -i HEAD~3

# Squash all commits in branch
git rebase -i $(git merge-base HEAD main)

# Force push safely
git push --force-with-lease origin feature-branch

# Undo last commit (keep changes)
git reset --soft HEAD~1

# Cherry-pick specific commit
git cherry-pick abc123

# Stash changes
git stash push -m "WIP: implementing feature X"
git stash pop

冲突解决：

# Pull latest with rebase
git pull --rebase origin main

# Use visual merge tool
git mergetool

# Accept their changes
git checkout --theirs <file>

# Accept your changes
git checkout --ours <file>

趋势认知协议

重要：当用户询问有关 Git 工作流、分支策略或协作工具的建议时，请在回答前通过网页搜索（和/或查看 data/sources.json 中的链接）核实当前趋势。

触发条件

• “对于 [团队规模/使用场景]，最佳 Git 工作流是什么？”
• “[分支管理/PR 管理] 应该用什么？”
• “Git 协作的最新趋势是什么？”
• “[分支管理/代码审查] 的当前最佳实践是什么？”
• “到 2026 年，[GitFlow/Trunk-Based] 还适用吗？”
• “[GitHub Flow]、[Trunk-Based] 和 [GitFlow] 怎么选？”
• “最佳 PR 堆叠工具是什么？”

必需的搜索

1. 搜索："Git workflow best practices 2026"
2. 搜索："[specific strategy] vs alternatives 2026"
3. 搜索："Git collaboration trends January 2026"
4. 搜索："[branching/PR tools] comparison 2026"

需要报告的内容

搜索后，提供：

• 当前格局：目前流行的 Git 工作流和工具
• 新兴趋势：日益普及的新协作模式、工具或实践
• 已弃用／渐趋式微：相关性或支持度正在下降的策略／工具
• 建议：基于最新数据，而非仅凭静态知识

示例主题（请通过最新搜索验证）

• 分支策略（Trunk-Based、GitHub Flow、GitFlow）
• PR 堆叠工具（Graphite、git-stack、Stacked PRs）
• 合并队列实现（GitHub、GitLab）
• 代码审查平台和自动化
• Conventional Commits 和变更日志工具
• Git 托管平台功能（GitHub、GitLab、Bitbucket）
• AI 辅助 Git 工作流