Back to Details

git-workflow

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Git Workflow

Git工作流

Effective version control is not just about tracking changes -- it is about enabling teams to collaborate predictably, release confidently, and maintain a history that tells a coherent story. The right workflow depends on team size, release cadence, and how much process the project can absorb without slowing down.
高效的版本控制不仅仅是追踪变更——它还能帮助团队实现可预测的协作、可靠的发布，并且维护一段逻辑连贯的变更历史。合适的工作流取决于团队规模、发布节奏，以及项目可承受且不会拖慢效率的流程复杂度。

Choosing a Branching Strategy

选择分支策略

No single branching model fits every team. The right choice depends on how often you release, how large your team is, and how much ceremony you can tolerate.
没有任何一种分支模型能适配所有团队。合适的选择取决于你的发布频率、团队规模，以及可接受的流程繁琐程度。

Strategy Comparison

策略对比

StrategyRelease CadenceTeam SizeComplexityBest For
Trunk-BasedContinuous (multiple per day)Any (works best with strong CI)LowSaaS, cloud-native, teams with mature CI/CD
GitHub FlowOn-demand (per merged PR)Small to mediumLowWeb apps, startups, teams wanting simplicity
Git FlowScheduled / versioned releasesMedium to largeHighPackaged software, mobile apps, multiple supported versions
GitLab FlowEnvironment-promotedMedium to largeMediumTeams needing environment-specific branches (staging, production)
策略发布节奏团队规模复杂度适用场景
Trunk-Based持续发布（每天多次）任意规模（搭配成熟CI效果最佳）低SaaS、云原生项目、拥有成熟CI/CD的团队
GitHub Flow按需发布（PR合并即发布）中小规模低Web应用、初创团队、追求简洁流程的团队
Git Flow定期/按版本发布中大规模高打包软件、移动应用、需要维护多个支持版本的项目
GitLab Flow按环境递进发布中大规模中等需要区分环境分支（预发、生产）的团队

Decision Guide

决策指南

  1. Do you deploy continuously? -- Use trunk-based development. Short-lived branches (hours, not days), feature flags for incomplete work, and strong CI are prerequisites.
  2. Do you deploy on merge but want review gates? -- Use GitHub Flow. One long-lived branch (main), feature branches, pull requests as the merge gate.
  3. Do you ship versioned releases on a schedule? -- Use Git Flow. Separate develop and main branches, release branches for stabilization, hotfix branches for emergency patches.
  4. Do you promote through environments? -- Use GitLab Flow. Environment branches (staging, production) sit downstream of main, and merges flow in one direction.
See Branching Strategies Reference for detailed mechanics, feature flag integration, and migration paths between strategies.
  1. 你是否需要持续部署？——使用基于主干的开发模式。前置要求为短生命周期分支（存续数小时而非数天）、未完工功能使用特性开关隐藏、拥有成熟的CI体系。
  2. 你是否在合并时部署，但需要评审关卡？——使用GitHub Flow。仅保留一个长期分支（main）、使用功能分支、以拉取请求作为合并准入门槛。
  3. 你是否按计划发布带版本号的版本？——使用Git Flow。拆分develop和main分支，用发布分支做版本固化，用热修复分支处理紧急补丁。
  4. 你是否需要跨环境递进发布？——使用GitLab Flow。环境分支（预发、生产）位于main分支下游，合并仅单向流动。
查看分支策略参考了解详细机制、特性开关集成以及不同策略之间的迁移路径。

Commit Message Conventions

提交信息规范

Good commit messages serve three audiences: reviewers reading the PR, developers reading 
git log
next month, and automation tools generating changelogs and version bumps.
优质的提交信息服务于三类受众：阅读PR的评审者、下个月查看
git log
的开发者、生成变更日志和版本号的自动化工具。

The Conventional Commits Format

约定式提交（Conventional Commits）格式

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

[optional body]

[optional footer(s)]
<type>(<scope>): <description>

[optional body]

[optional footer(s)]

Common Commit Types

常用提交类型

TypePurposeVersion Impact
feat
New feature visible to usersMinor bump
fix
Bug fixPatch bump
refactor
Code restructuring with no behavior changeNone
perf
Performance improvementPatch bump
test
Adding or updating testsNone
docs
Documentation onlyNone
chore
Tooling, dependencies, build configNone
ci
CI/CD pipeline changesNone
build
Build system or dependency changesNone
类型用途版本影响
feat
用户可见的新功能次版本号升级
fix
Bug修复修订版本号升级
refactor
不改变行为的代码重构无影响
perf
性能优化修订版本号升级
test
新增或更新测试用例无影响
docs
仅文档变更无影响
chore
工具链、依赖、构建配置变更无影响
ci
CI/CD流水线变更无影响
build
构建系统或依赖变更无影响

Breaking Changes

破坏性变更

Append 
!
after the type or add a 
BREAKING CHANGE:
footer to signal incompatible changes. Either notation triggers a major version bump when used with automated release tooling.
feat(api)!: remove deprecated /v1/users endpoint

BREAKING CHANGE: The /v1/users endpoint has been removed. Use /v2/users instead.
在类型后追加
!
或者添加
BREAKING CHANGE:
页脚来标记不兼容变更。当搭配自动化发布工具使用时，任意一种标记都会触发主版本号升级。
feat(api)!: remove deprecated /v1/users endpoint

BREAKING CHANGE: The /v1/users endpoint has been removed. Use /v2/users instead.

Semantic Versioning Alignment

语义化版本对齐

Commit ContainsVersion BumpExample
fix:
Patch (1.0.0 -> 1.0.1)Bug corrections
feat:
Minor (1.0.0 -> 1.1.0)New capabilities
BREAKING CHANGE
or 
!
Major (1.0.0 -> 2.0.0)Incompatible changes
See Commit Conventions Reference for scope naming patterns, multi-line body guidelines, changelog automation setup, and git hook validation.
提交包含内容版本号升级示例
fix:
修订号（1.0.0 -> 1.0.1）Bug修复
feat:
次版本号（1.0.0 -> 1.1.0）新增功能
BREAKING CHANGE
或 
!
主版本号（1.0.0 -> 2.0.0）不兼容变更
查看提交规范参考了解范围命名模式、多行正文规范、变更日志自动化配置以及Git钩子校验方法。

Pull Request Workflow

拉取请求（PR）工作流

Pull requests are the primary collaboration point in most git workflows. Their quality directly affects review speed, defect discovery, and team velocity.
拉取请求是大多数Git工作流中的核心协作节点。它的质量直接影响评审速度、缺陷发现效率和团队迭代速度。

PR Size Guidelines

PR规模指引

PR Size (lines changed)Review QualityRecommended
< 50Excellent -- reviewer catches most issuesIdeal for stacked PRs
50-200Good -- manageable cognitive loadSweet spot for most changes
200-400Acceptable -- requires focused review timeUpper bound for single reviews
400+Poor -- reviewer fatigue, defects slip throughSplit into smaller PRs
PR规模（变更行数）评审质量推荐程度
< 50优秀——评审者能发现绝大多数问题堆叠PR的理想选择
50-200良好——认知负荷可控绝大多数变更的最优区间
200-400可接受——需要集中评审时间单次评审的上限
400+较差——评审者疲劳，缺陷容易遗漏拆分为更小的PR

Core PR Practices

核心PR实践

  • One concern per PR -- A PR should do one thing: add a feature, fix a bug, refactor a module. Mixing concerns makes review harder and reverts riskier.
  • Write a clear description -- State what changed, why it changed, and how to verify it. Link to the relevant ticket or issue.
  • Keep the diff reviewable -- Move large mechanical changes (renames, formatting) into separate PRs from logic changes.
  • Respond to feedback promptly -- Stale PRs accumulate merge conflicts and block dependent work.
  • 每个PR仅解决一个问题——一个PR应该只做一件事：新增功能、修复Bug、重构某个模块。混合多个变更会提升评审难度，也会提高回滚风险。
  • 编写清晰的描述——说明变更内容、变更原因以及验证方法，关联对应的工单或Issue。
  • 保持diff可评审——将大量机械变更（重命名、格式化）和逻辑变更拆分到不同的PR中。
  • 及时响应评审反馈——搁置的PR容易产生合并冲突，也会阻塞依赖它的后续工作。

Merge Strategies

合并策略

StrategyHistory ShapeBest For
Merge commitPreserves branch topology, creates merge nodeOpen-source projects, audit trails
Squash and mergeCollapses branch into single commit on mainFeature branches with messy intermediate commits
Rebase and mergeLinear history, no merge commitsTeams wanting clean, linear logs
See PR Patterns Reference for description templates, CODEOWNERS configuration, branch protection rules, stacked PR workflows, and review assignment strategies.
策略历史结构适用场景
合并提交（Merge commit）保留分支拓扑，生成合并节点开源项目、需要审计轨迹的场景
压缩合并（Squash and merge）将分支所有提交压缩为main分支上的单个提交中间提交混乱的功能分支
变基合并（Rebase and merge）线性历史，无合并提交追求整洁线性提交日志的团队
查看PR模式参考了解描述模板、CODEOWNERS配置、分支保护规则、堆叠PR工作流以及评审分配策略。

Release Management

发布管理

Release management bridges development and deployment. The approach depends on whether releases are continuous, scheduled, or versioned.
发布管理是开发和部署之间的桥梁。具体方案取决于发布是持续式、定期式还是按版本发布。

Release Models

发布模型

ModelHow It WorksWhen to Use
Continuous releaseEvery merged PR deploys automaticallySaaS with strong CI/CD and monitoring
Scheduled releaseChanges accumulate, release on a cadence (weekly, biweekly)Teams needing coordination windows
Versioned releaseExplicit version tags, release branches for stabilizationLibraries, APIs, packaged software
模型工作方式适用场景
持续发布每个合并的PR自动部署拥有成熟CI/CD和监控体系的SaaS产品
定期发布变更累积后按固定节奏发布（每周、每两周）需要协调发布窗口的团队
按版本发布显式标记版本号，用发布分支做版本固化类库、API、打包软件

Git Tags for Releases

用于发布的Git标签

Tags mark specific commits as release points. Use annotated tags for releases because they store author, date, and message metadata.
bash
undefined
标签将特定提交标记为发布节点。推荐使用附注标签做发布标记，因为它们会存储作者、日期和消息元数据。
bash
undefined

Create an annotated release tag

创建一个附注发布标签

git tag -a v1.2.0 -m "Release 1.2.0: Add user dashboard and fix auth timeout"
git tag -a v1.2.0 -m "Release 1.2.0: Add user dashboard and fix auth timeout"

Push tags to remote

推送标签到远程仓库

git push origin v1.2.0
git push origin v1.2.0

List existing tags matching a pattern

列出匹配指定模式的现有标签

git tag -l "v1.*"
undefined
git tag -l "v1.*"
undefined

Automated Release Pipeline

自动化发布流水线

When conventional commits are combined with release automation tooling, the pipeline can:
  1. Analyze commits since the last tag to determine the next version
  2. Generate or update the changelog from commit messages
  3. Create the git tag
  4. Build and publish artifacts
  5. Create a release entry on the hosting platform (GitHub/GitLab)
This eliminates manual version decisions and ensures the changelog stays synchronized with actual changes.
当约定式提交搭配发布自动化工具使用时，流水线可以：
  1. 分析上一个标签以来的所有提交，确定下一个版本号
  2. 根据提交信息生成或更新变更日志
  3. 创建Git标签
  4. 构建并发布制品
  5. 在代码托管平台（GitHub/GitLab）上创建发布条目
这可以消除手动版本决策的成本，确保变更日志和实际变更保持同步。

Hotfix Workflow

热修复工作流

When a critical bug is found in production:
  1. Branch from the release tag (not from the development branch)
  2. Apply the minimal fix
  3. Tag the new patch release
  4. Merge the fix forward into the main development line to prevent regression
bash
undefined
当生产环境发现严重Bug时：
  1. 从发布标签切出分支（不要从开发分支切）
  2. 提交最小化修复方案
  3. 标记新的补丁版本标签
  4. 将修复向前合并到主开发分支，避免后续版本出现回归
bash
undefined

Branch from the release tag

从发布标签切出分支

git checkout -b hotfix/fix-auth-crash v1.2.0
git checkout -b hotfix/fix-auth-crash v1.2.0

After fixing and committing

修复并提交后

git tag -a v1.2.1 -m "Hotfix: prevent auth crash on expired tokens" git push origin v1.2.1
git tag -a v1.2.1 -m "Hotfix: prevent auth crash on expired tokens" git push origin v1.2.1

Merge fix back to main

将修复合并回main分支

git checkout main git merge hotfix/fix-auth-crash

---
git checkout main git merge hotfix/fix-auth-crash

---

Quick Reference: Common Workflow Problems

快速参考：常见工作流问题

ProblemLikely CauseResolution
Frequent merge conflictsLong-lived branches, infrequent integrationMerge main into feature branches daily, or switch to trunk-based
Broken main branchNo CI on PRs, insufficient test coverageRequire passing CI before merge, add branch protection
Unclear release contentsNo commit conventions, manual changelogsAdopt conventional commits, automate changelog generation
Slow PR reviewsPRs too large, no clear ownershipSet size guidelines, configure CODEOWNERS, use stacked PRs
Accidental commits to mainNo branch protectionEnable branch protection rules, require PR reviews
问题可能原因解决方案
频繁出现合并冲突分支生命周期长、集成频率低每天将main分支合并到功能分支，或者切换到基于主干的开发模式
main分支被破坏PR没有经过CI校验、测试覆盖不足要求合并前CI必须通过，添加分支保护规则
发布内容不清晰没有提交规范、手动维护变更日志采用约定式提交，自动化生成变更日志
PR评审速度慢PR过大、没有明确责任人设定PR规模指引、配置CODEOWNERS、使用堆叠PR
意外提交到main分支没有分支保护开启分支保护规则，要求必须经过PR评审才能合并

Reference Files

参考文件

ReferenceContents
Branching StrategiesTrunk-based, GitHub Flow, Git Flow, GitLab Flow -- mechanics, feature flags, comparison matrix
Commit ConventionsConventional commits format, scope patterns, semantic versioning, changelog automation, git hooks
PR PatternsSize guidelines, description templates, CODEOWNERS, merge strategies, branch protection, stacked PRs
参考文档内容
分支策略基于主干开发、GitHub Flow、Git Flow、GitLab Flow——实现机制、特性开关、对比矩阵
提交规范约定式提交格式、范围模式、语义化版本、变更日志自动化、Git钩子
PR模式规模指引、描述模板、CODEOWNERS、合并策略、分支保护、堆叠PR

Integration with Other Skills

与其他技能的集成

SituationRecommended Skill
Setting up CI/CD pipelines for branch protectionInstall 
knowledge-virtuoso
from 
krzysztofsurdy/code-virtuoso
for testing strategies
API versioning aligned with git release tagsInstall 
knowledge-virtuoso
from 
krzysztofsurdy/code-virtuoso
for API design principles
Coordinating releases across microservicesInstall 
knowledge-virtuoso
from 
krzysztofsurdy/code-virtuoso
for microservices patterns
Sprint-aligned release planningInstall 
knowledge-virtuoso
from 
krzysztofsurdy/code-virtuoso
for scrum workflows
场景推荐技能
配置用于分支保护的CI/CD流水线从
krzysztofsurdy/code-virtuoso
安装
knowledge-virtuoso
获取测试策略相关内容
与Git发布标签对齐的API版本控制从
krzysztofsurdy/code-virtuoso
安装
knowledge-virtuoso
获取API设计原则相关内容
跨微服务的发布协调从
krzysztofsurdy/code-virtuoso
安装
knowledge-virtuoso
获取微服务模式相关内容
与Sprint对齐的发布规划从
krzysztofsurdy/code-virtuoso
安装
knowledge-virtuoso
获取Scrum工作流相关内容