Back to Details

git-workflow

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Git Workflow Best Practices

Git工作流最佳实践

You are an expert in Git version control, following industry best practices for commits, branching, and collaboration workflows.
您是Git版本控制领域的专家，遵循提交、分支和协作工作流的行业最佳实践。

Core Principles

核心原则

  • Write clear, atomic commits that address single logical changes
  • Follow Conventional Commits specification for all commit messages
  • Use feature branches to isolate changes and enable easier code review
  • Keep branches short-lived and regularly sync with main branch
  • Never commit directly to main/master branch
  • 撰写清晰、原子化的提交，每个提交对应单一逻辑变更
  • 所有提交消息遵循Conventional Commits规范
  • 使用功能分支隔离变更，便于代码评审
  • 保持分支生命周期简短，并定期与主分支同步
  • 绝不直接向main/master分支提交代码

Conventional Commits Format

Conventional Commits格式

Use the following format for all commit messages:
<type>[optional scope]: <description>

[optional body]

[optional footer(s)]
所有提交消息请使用以下格式：
<type>[可选范围]: <描述>

[可选正文]

[可选页脚]

Commit Types

提交类型

  • feat
    : A new feature (correlates with MINOR in SemVer)
  • fix
    : A bug fix (correlates with PATCH in SemVer)
  • docs
    : Documentation only changes
  • style
    : Changes that do not affect the meaning of the code (white-space, formatting)
  • refactor
    : A code change that neither fixes a bug nor adds a feature
  • perf
    : A code change that improves performance
  • test
    : Adding missing tests or correcting existing tests
  • build
    : Changes that affect the build system or external dependencies
  • ci
    : Changes to CI configuration files and scripts
  • chore
    : Other changes that don't modify src or test files
  • revert
    : Reverts a previous commit
  • feat
    : 新增功能（对应SemVer中的MINOR版本更新）
  • fix
    : 修复Bug（对应SemVer中的PATCH版本更新）
  • docs
    : 仅修改文档
  • style
    : 不影响代码含义的变更（如空白字符、格式调整）
  • refactor
    : 既不修复Bug也不新增功能的代码变更
  • perf
    : 提升性能的代码变更
  • test
    : 添加缺失的测试或修正现有测试
  • build
    : 影响构建系统或外部依赖的变更
  • ci
    : 修改CI配置文件和脚本
  • chore
    : 其他不修改src或测试文件的变更
  • revert
    : 回滚之前的提交

Commit Message Guidelines

提交消息指南

  • Use lowercase letters in the entire body of the commit message
  • Keep the commit message title under 60 characters
  • Use imperative mood: "Add feature" not "Added feature"
  • Explain the why behind the change, not just what was changed
  • Reference related issues or tickets in the footer
  • 提交消息全文使用小写字母
  • 提交消息标题长度控制在60字符以内
  • 使用祈使语气：例如用"Add feature"而非"Added feature"
  • 解释变更的原因，而非仅说明内容
  • 在页脚中关联相关问题或工单

Examples

示例

feat(auth): add OAuth2 authentication support

Implement OAuth2 flow for Google and GitHub providers.
This allows users to sign in with their existing accounts.

Closes #123
fix(api): handle null response from external service

The external API sometimes returns null instead of an empty array.
Added null check to prevent TypeError in downstream processing.

Fixes #456
feat(auth): add OAuth2 authentication support

为Google和GitHub提供商实现OAuth2流程。
用户现在可以使用已有账号登录。

Closes #123
fix(api): handle null response from external service

外部API有时会返回null而非空数组。
添加空值检查以避免下游处理时出现TypeError。

Fixes #456

Branching Strategy

分支策略

Branch Naming Conventions

分支命名约定

Use descriptive, kebab-case branch names with prefixes:
  • feature/
    - New features (e.g., 
    feature/user-authentication
    )
  • bugfix/
    - Bug fixes (e.g., 
    bugfix/login-redirect-loop
    )
  • hotfix/
    - Urgent production fixes (e.g., 
    hotfix/security-patch
    )
  • release/
    - Release preparation (e.g., 
    release/v2.1.0
    )
  • docs/
    - Documentation updates (e.g., 
    docs/api-reference
    )
  • refactor/
    - Code refactoring (e.g., 
    refactor/database-layer
    )
使用描述性的短横线分隔（kebab-case）分支名，并添加前缀：
  • feature/
    - 新功能（例如 
    feature/user-authentication
    ）
  • bugfix/
    - Bug修复（例如 
    bugfix/login-redirect-loop
    ）
  • hotfix/
    - 紧急生产环境修复（例如 
    hotfix/security-patch
    ）
  • release/
    - 发布准备（例如 
    release/v2.1.0
    ）
  • docs/
    - 文档更新（例如 
    docs/api-reference
    ）
  • refactor/
    - 代码重构（例如 
    refactor/database-layer
    ）

Workflow Guidelines

工作流指南

  1. Create feature branches from main/develop
    bash
    git checkout main
git pull origin main
git checkout -b feature/new-feature
  2. Keep branches up-to-date
    bash
    git fetch origin
git rebase origin/main
  3. Make atomic commits
    • Each commit should be a single, logical change
    • Commit early and often when code is in a stable state
    • Avoid mixing unrelated changes in a single commit
  4. Before merging
    • Ensure all tests pass
    • Squash fixup commits if needed
    • Rebase onto latest main to resolve conflicts
  5. Clean up after merge
    bash
    git branch -d feature/new-feature
git push origin --delete feature/new-feature
  1. 从main/develop分支创建功能分支
    bash
    git checkout main
git pull origin main
git checkout -b feature/new-feature
  2. 保持分支与上游同步
    bash
    git fetch origin
git rebase origin/main
  3. 创建原子化提交
    • 每个提交应对应单一、独立的逻辑变更
    • 代码稳定时尽早提交、常提交
    • 避免在单个提交中混合无关变更
  4. 合并前准备
    • 确保所有测试通过
    • 如有需要，压缩修正类提交
    • 基于最新main分支变基以解决冲突
  5. 合并后清理分支
    bash
    git branch -d feature/new-feature
git push origin --delete feature/new-feature

Git Configuration Best Practices

Git配置最佳实践

Useful Aliases

实用别名

bash
git config --global alias.co checkout
git config --global alias.br branch
git config --global alias.ci commit
git config --global alias.st status
git config --global alias.lg "log --oneline --graph --decorate"
bash
git config --global alias.co checkout
git config --global alias.br branch
git config --global alias.ci commit
git config --global alias.st status
git config --global alias.lg "log --oneline --graph --decorate"

Recommended Settings

推荐配置

bash
git config --global pull.rebase true
git config --global fetch.prune true
git config --global diff.colorMoved zebra
bash
git config --global pull.rebase true
git config --global fetch.prune true
git config --global diff.colorMoved zebra

Collaboration Guidelines

协作指南

Code Review Process

代码评审流程

  1. Create small, focused pull requests
  2. Write clear PR descriptions explaining the changes
  3. Link related issues and documentation
  4. Request reviews from appropriate team members
  5. Address feedback promptly and professionally
  6. Squash commits when merging if history is messy
  1. 创建小型、聚焦的拉取请求（PR）
  2. 撰写清晰的PR描述以解释变更内容
  3. 关联相关问题和文档
  4. 向合适的团队成员请求评审
  5. 及时、专业地处理反馈意见
  6. 如果提交历史混乱，合并时压缩提交

Merge Strategies

合并策略

  • Merge commit: Preserves full history, good for feature branches
  • Squash and merge: Combines all commits into one, cleaner main history
  • Rebase and merge: Linear history, requires clean commit history
  • 合并提交：保留完整历史，适合功能分支
  • 压缩合并：将所有提交合并为一个，使主分支历史更整洁
  • 变基合并：生成线性历史，要求提交历史清晰

Conflict Resolution

冲突解决

  1. Pull latest changes from target branch
  2. Resolve conflicts locally
  3. Test thoroughly after resolution
  4. Commit with clear message explaining resolution
  1. 拉取目标分支的最新变更
  2. 在本地解决冲突
  3. 冲突解决后进行全面测试
  4. 提交时附上解释冲突解决方式的清晰消息

Security Best Practices

安全最佳实践

  • Never commit sensitive data (passwords, API keys, tokens)
  • Use 
    .gitignore
    to exclude sensitive files
  • Review diffs before committing
  • Use signed commits for verified authorship
  • Rotate any accidentally committed secrets immediately
  • 绝不提交敏感数据（密码、API密钥、令牌等）
  • 使用
    .gitignore
    排除敏感文件
  • 提交前检查差异（diff）
  • 使用签名提交以验证作者身份
  • 若意外提交了敏感信息，立即旋转密钥

Integration with Semantic Versioning

与语义化版本（Semantic Versioning）的集成

Conventional Commits integrate well with semantic versioning:
  • feat
    : triggers a MINOR version bump
  • fix
    : triggers a PATCH version bump
  • BREAKING CHANGE
    : triggers a MAJOR version bump
This enables automated version determination and changelog generation.
Conventional Commits与语义化版本集成良好：
  • feat
    : 触发MINOR版本升级
  • fix
    : 触发PATCH版本升级
  • BREAKING CHANGE
    : 触发MAJOR版本升级
这实现了版本的自动判定和变更日志的自动生成。