git-workflow

Git 工作流

涵盖分支策略、约定式提交、CI/CD 自动化、仓库卫生和 Git 内部机制。GitHub CLI 的用法由单独的 github-cli 技能处理；本技能侧重于 Git 工作流模式和 CI/CD 配置。

快速参考

领域	关键实践
分支	采用主干开发，使用短期功能分支
提交	使用约定式提交，采用祈使语气
历史	通过变基保持线性历史；压缩杂乱提交
PR	保持改动小而独立；避免超大型 PR
主分支	始终可部署；主分支损坏时按紧急情况处理
CI/CD	使用模块化 GitHub Actions 和可复用工作流
合并	合并前必须通过 CI 并获得审查
版本管理	使用 Semantic Release 或 Changesets（绝不手动管理）
分支	生命周期最长 48 小时；自动清理过期或已合并的分支
密钥	在流水线中使用 OIDC Connect；绝不硬编码令牌
签名	使用 SSH 或 GPG 密钥签署提交，以验证作者身份

分支命名

类型	用途	示例
feat	新功能	feat/add-user-auth
fix	Bug 修复	fix/login-redirect
chore	维护工作	chore/update-deps
docs	文档	docs/api-reference
refactor	代码重构	refactor/auth-module

约定式提交类型

类型	用途	版本升级
feat	新功能	次版本
fix	Bug 修复	修订版本
docs	仅文档	无
style	格式调整，不更改逻辑	无
refactor	既非修复也非新功能	无
perf	性能改进	修订版本
test	添加或修正测试	无
build	构建系统或外部依赖	无
ci	CI 配置变更	无
chore	工具、维护及非源代码变更	无
revert	撤销之前的提交	视情况而定

对于破坏性变更，在类型／范围后添加 !（主版本升级）。

合并前检查

所有 PR 在合并前都必须完成以下检查：

• Lint
• 类型检查
• 测试
• 安全扫描
• 审查批准（人工或自动化）

对于低风险 PR，如果流水线成功，则可以自动合并。

故障排查

问题	解决方法
长期分支出现合并冲突	经常变基到 main；如果剩余工作超过 48 小时，则拆分到新分支
主分支损坏	按紧急情况处理；撤销导致问题的提交，然后在分支上修复
提交丢失或数据恢复	使用 git reflog 和对象检查（git cat-file、git fsck）
CI 流水线失败	检查可复用工作流版本；验证 OIDC 权限
变基后堆叠 PR 冲突	从基准分支重新整理整个链；Graphite 可通过 gt restack 自动处理
意外提交大型文件	使用 git filter-repo 从历史记录中移除（不要使用 git filter-branch）

常见错误

错误	正确做法
功能分支存续时间超过 48 小时	每天合并或变基；将大型工作拆分为堆叠式 PR
未启用分支保护便直接提交到 main	启用分支保护规则，要求通过 CI 并完成审查
使用合并提交，导致历史记录杂乱	变基并压缩提交，以保持线性历史记录
在 GitHub Actions 工作流中硬编码令牌	在 CI/CD 流水线中使用 OIDC Connect 进行身份验证
在单个文件中创建庞大的 CI 工作流	拆分为可复用工作流和复合操作
将 Fix bug 作为提交消息	使用 fix(scope): correct bug description（符合约定）
使用 feat: Added feature（过去时）	使用 feat: add feature（祈使语气，首字母小写）
使用 git filter-branch 重写历史记录	使用 git filter-repo（速度更快、更安全，且为官方推荐）
直接推送到 main	先创建功能分支
在共享仓库中提交未签名的提交	使用 SSH 或 GPG 密钥配置提交签名

委派

• 审查仓库的分支管理规范性和陈旧分支：使用 Explore Agent 列出并分类分支的存续时间和合并状态
• 使用可复用工作流搭建 CI/CD 流水线：使用 Task Agent 创建模块化的 GitHub Actions 配置
• 为新项目设计分支策略：使用 Plan Agent，根据团队需求评估主干开发与 Git Flow

参考资料

• branching-strategies.md -- Git Flow、GitHub Flow、GitLab Flow、One-Flow 的比较和选择标准
• trunk-based-development.md -- 核心原则、工作流步骤、功能标志和反模式
• stacked-changes.md -- 堆叠式 PR 的概念、手动堆叠、Graphite 自动化和最佳实践
• conventional-commits.md -- 提交格式、类型、范围、破坏性变更和完整工作流
• github-actions.md -- 可复用工作流、矩阵测试、部署环境和安全
• git-internals.md -- 对象模型、SHA 哈希、索引、引用、包文件和垃圾回收
• automation-scripts.md -- 分支清理、语义化发布、安全扫描和堆叠式 PR 辅助工具
• issue-templates.md -- 错误报告、功能请求、任务和精简问题模板
• advanced-operations.md -- 提交签名、交互式变基、工作树、二分查找、reflog 恢复和 --force-with-lease