Back to Details

git-workflow

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Git Workflow

Git工作流

Covers branching strategies, conventional commits, CI/CD automation, repository hygiene, and git internals. GitHub CLI usage is handled by a separate 
github-cli
skill; this skill focuses on git workflow patterns and CI/CD configuration.
涵盖分支策略、规范提交、CI/CD自动化、仓库整洁性管理以及Git内部原理。GitHub CLI的使用由独立的
github-cli
技能负责；本技能专注于Git工作流模式和CI/CD配置。

Quick Reference

快速参考

AreaKey Practice
BranchingTrunk-based development with short-lived feature branches
CommitsConventional commits with imperative mood
HistoryLinear history via rebase; squash noisy commits
PRsSmall, stacked changes; no mega PRs
Main branchAlways deployable; broken main is an emergency
CI/CDModular GitHub Actions with reusable workflows
MergingGreen CI + review required before merge
VersioningSemantic Release or Changesets (never manual)
BranchesMax 48 hours lifespan; auto-prune stale/merged
SecretsOIDC Connect in pipelines; never hardcode tokens
SigningSign commits with SSH or GPG keys for verified authorship
领域核心实践
分支管理基于主干的开发搭配短期特性分支
提交规范使用命令式语气的规范提交
提交历史通过变基实现线性历史；压缩冗余提交
拉取请求（PR）小型、堆叠式变更；避免巨型PR
主分支始终可部署；主分支故障属于紧急情况
CI/CD采用可复用工作流的模块化GitHub Actions
合并合并前需通过CI检查并获得审核通过
版本控制使用Semantic Release或Changesets（禁止手动操作）
分支生命周期最长48小时存活期；自动清理已合并或陈旧分支
密钥管理在流水线中使用OIDC Connect；绝不硬编码令牌
提交签名使用SSH或GPG密钥签名提交以验证作者身份

Branch Naming

分支命名规范

TypeUse ForExample
featNew features
feat/add-user-auth
fixBug fixes
fix/login-redirect
choreMaintenance
chore/update-deps
docsDocumentation
docs/api-reference
refactorCode restructuring
refactor/auth-module
类型适用场景示例
feat新功能开发
feat/add-user-auth
fixBug修复
fix/login-redirect
chore维护性工作
chore/update-deps
docs文档更新
docs/api-reference
refactor代码重构
refactor/auth-module

Conventional Commit Types

规范提交类型

TypePurposeVersion Bump
feat
New featuresMinor
fix
Bug fixesPatch
docs
Documentation onlyNone
style
Formatting, no logic changesNone
refactor
Neither fix nor featureNone
perf
Performance improvementsPatch
test
Adding or correcting testsNone
build
Build system or external dependenciesNone
ci
CI configuration changesNone
chore
Tooling, maintenance, non-src changesNone
revert
Revert a previous commitVaries
Append 
!
after type/scope for breaking changes (major version bump).
类型用途版本变更
feat
新增功能次要版本（Minor）
fix
Bug修复补丁版本（Patch）
docs
仅更新文档无
style
格式调整，无逻辑变更无
refactor
既非修复也非新增功能无
perf
性能优化补丁版本（Patch）
test
添加或修正测试用例无
build
构建系统或外部依赖变更无
ci
CI配置变更无
chore
工具维护、非源码变更无
revert
回滚之前的提交视情况而定
在类型/作用域后追加
!
表示破坏性变更（主版本号升级）。

Pre-Merge Checks

合并前检查

All PRs require before merge:
  • Lint
  • Type check
  • Tests
  • Security scan
  • Review approval (human or automated)
Auto-merge is acceptable for low-risk PRs when pipeline succeeds.
所有PR在合并前必须满足：
  • 代码检查（Lint）
  • 类型检查
  • 测试通过
  • 安全扫描
  • 审核通过（人工或自动化）
低风险PR在流水线执行成功后可启用自动合并。

Troubleshooting

故障排查

IssueResolution
Merge conflicts on long-running branchRebase onto main frequently; break remaining work into new branch if over 48 hours
Broken main branchTreat as emergency; revert offending commit, then fix forward on a branch
Lost commits or data recoveryUse git reflog and object inspection (
git cat-file
, 
git fsck
)
CI pipeline failuresCheck reusable workflow versions; verify OIDC permissions
Stacked PR conflicts after rebaseRestack entire chain from base; Graphite handles automatically with 
gt restack
Large file accidentally committedUse 
git filter-repo
to remove from history (not 
git filter-branch
)
问题解决方案
长期分支出现合并冲突频繁基于主分支变基；若超过48小时，将剩余工作拆分为新分支
主分支故障视为紧急情况；回滚有问题的提交，随后在分支上进行正向修复
丢失提交或数据恢复使用git reflog和对象检查命令（
git cat-file
, 
git fsck
）
CI流水线失败检查可复用工作流版本；验证OIDC权限
变基后堆叠PR出现冲突从基础分支重新堆叠整个链；使用Graphite的
gt restack
命令可自动处理
意外提交大文件使用
git filter-repo
从历史中移除（请勿使用
git filter-branch
）

Common Mistakes

常见错误

MistakeCorrect Pattern
Keeping feature branches alive longer than 48 hoursMerge or rebase daily; break large work into stacked PRs
Committing directly to main without branch protectionEnable branch protection rules requiring CI and review
Using merge commits that clutter historyRebase and squash to maintain linear history
Hardcoding tokens in GitHub Actions workflowsUse OIDC Connect for authentication in CI/CD pipelines
Creating monolithic CI workflows in a single fileSplit into reusable workflows and composite actions
Fix bug
as commit message
fix(scope): correct bug description
(conventional)
feat: Added feature
(past tense)
feat: add feature
(imperative mood, lowercase)
Using 
git filter-branch
for history rewriting		Use 
git filter-repo
(faster, safer, officially recommended)
Pushing to main directlyCreate feature branch first
Unsigned commits in shared repositoriesConfigure commit signing with SSH or GPG keys
错误操作正确实践
特性分支存活超过48小时每日合并或变基；将大型工作拆分为堆叠PR
无分支保护时直接提交到主分支启用分支保护规则，要求通过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
（更快、更安全，官方推荐）
直接推送到主分支先创建特性分支
共享仓库中存在未签名的提交配置使用SSH或GPG密钥进行提交签名

Delegation

任务委派

  • Audit repository branch hygiene and stale branches: Use 
    Explore
    agent to list and classify branch age and merge status
  • Set up CI/CD pipelines with reusable workflows: Use 
    Task
    agent to create modular GitHub Actions configurations
  • Design branching strategy for a new project: Use 
    Plan
    agent to evaluate trunk-based vs Git Flow based on team needs
  • 审核仓库分支整洁性和陈旧分支：使用
    Explore
    agent列出并分类分支的存活时长和合并状态
  • 搭建带可复用工作流的CI/CD流水线：使用
    Task
    agent创建模块化GitHub Actions配置
  • 为新项目设计分支策略：使用
    Plan
    agent根据团队需求评估基于主干的开发与Git Flow的优劣

References

参考资料

  • branching-strategies.md -- Git Flow, GitHub Flow, GitLab Flow, One-Flow comparison and selection criteria
  • trunk-based-development.md -- Core principles, workflow steps, feature flags, and anti-patterns
  • stacked-changes.md -- Stacked PRs concept, manual stacking, Graphite automation, best practices
  • conventional-commits.md -- Commit format, types, scopes, breaking changes, and full workflow
  • github-actions.md -- Reusable workflows, matrix testing, deployment environments, security
  • git-internals.md -- Object model, SHA hashing, index, references, packfiles, garbage collection
  • automation-scripts.md -- Branch pruning, semantic release, security scanning, stacked PR helpers
  • issue-templates.md -- Bug report, feature request, task, and minimal issue templates
  • advanced-operations.md -- Commit signing, interactive rebase, worktrees, bisect, reflog recovery, and --force-with-lease
  • 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 -- Bug报告、功能请求、任务及极简问题模板
  • advanced-operations.md -- 提交签名、交互式变基、工作树、二分查找、Reflog恢复及--force-with-lease参数