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

工作流指南

Create feature branches from main/develop

bash

git checkout main
git pull origin main
git checkout -b feature/new-feature

Keep branches up-to-date
bash
```
git fetch origin
git rebase origin/main
```
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
Before merging
- Ensure all tests pass
- Squash fixup commits if needed
- Rebase onto latest main to resolve conflicts

Clean up after merge

bash

git branch -d feature/new-feature
git push origin --delete feature/new-feature

从main/develop分支创建功能分支

bash

git checkout main
git pull origin main
git checkout -b feature/new-feature

保持分支与上游同步
bash
```
git fetch origin
git rebase origin/main
```
创建原子化提交
- 每个提交应对应单一、独立的逻辑变更
- 代码稳定时尽早提交、常提交
- 避免在单个提交中混合无关变更
合并前准备
- 确保所有测试通过
- 如有需要，压缩修正类提交
- 基于最新main分支变基以解决冲突

合并后清理分支

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

Collaboration Guidelines

协作指南

Code Review Process

代码评审流程

Create small, focused pull requests
Write clear PR descriptions explaining the changes
Link related issues and documentation
Request reviews from appropriate team members
Address feedback promptly and professionally
Squash commits when merging if history is messy

创建小型、聚焦的拉取请求（PR）
撰写清晰的PR描述以解释变更内容
关联相关问题和文档
向合适的团队成员请求评审
及时、专业地处理反馈意见
如果提交历史混乱，合并时压缩提交

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

冲突解决

Pull latest changes from target branch
Resolve conflicts locally
Test thoroughly after resolution
Commit with clear message explaining resolution

拉取目标分支的最新变更
在本地解决冲突
冲突解决后进行全面测试
提交时附上解释冲突解决方式的清晰消息

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版本升级

这实现了版本的自动判定和变更日志的自动生成。

git-workflow

Original

Translation

Git Workflow Best Practices

Git工作流最佳实践

Core Principles

核心原则

Conventional Commits Format

Conventional Commits格式

Commit Types

提交类型

Commit Message Guidelines

提交消息指南

Examples

示例

Branching Strategy

分支策略

Branch Naming Conventions

分支命名约定

Workflow Guidelines

工作流指南

Git Configuration Best Practices

Git配置最佳实践

Useful Aliases

实用别名

Recommended Settings

推荐配置

Collaboration Guidelines

协作指南

Code Review Process

代码评审流程

Merge Strategies

合并策略

Conflict Resolution

冲突解决

Security Best Practices

安全最佳实践

Integration with Semantic Versioning

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