Git Workflow

Git 工作流

Git best practices, commit conventions, branching strategies, and pull request workflows. Guidelines for maintaining a clean, useful git history.

Git最佳实践、Commit规范、分支策略及PR工作流。维护清晰、实用Git历史记录的指南。

When to Apply

适用场景

Reference these guidelines when:

Writing commit messages
Creating branches
Setting up git workflows
Reviewing pull requests
Maintaining git history

在以下场景可参考本指南：

编写Commit信息
创建分支
配置Git工作流
评审PR
维护Git历史记录

Rule Categories by Priority

按优先级划分的规则类别


commit-
branch-
pr-
history-
collab-

Priority	Category	Impact	Prefix
1	Commit Messages	CRITICAL	`commit-`
2	Branching Strategy	HIGH	`branch-`
3	Pull Requests	HIGH	`pr-`
4	History Management	MEDIUM	`history-`
5	Collaboration	MEDIUM	`collab-`


commit-
branch-
pr-
history-
collab-

优先级	类别	影响级别	前缀
1	Commit 信息	关键	`commit-`
2	分支策略	高	`branch-`
3	PR	高	`pr-`
4	历史记录管理	中	`history-`
5	协作	中	`collab-`

Quick Reference

快速参考

1. Commit Messages (CRITICAL)

1. Commit 信息（关键）

```
commit-conventional
```
- Use conventional commits
```
commit-atomic
```
- Atomic commits (one logical change)
```
commit-present-tense
```
- Use imperative present tense
```
commit-meaningful
```
- Descriptive, meaningful messages
```
commit-body
```
- Add body for complex changes
```
commit-references
```
- Reference issues/tickets
```
commit-git-hooks
```
- Enforce standards with Husky + commitlint

```
commit-conventional
```
- 使用约定式Commit
```
commit-atomic
```
- 原子化Commit（单个逻辑变更）
```
commit-present-tense
```
- 使用祈使式现在时
```
commit-meaningful
```
- 描述性、有意义的信息
```
commit-body
```
- 为复杂变更添加正文
```
commit-references
```
- 关联议题/工单
```
commit-git-hooks
```
- 使用Husky + commitlint强制执行规范

2. Branching Strategy (HIGH)

2. 分支策略（高）

```
branch-naming
```
- Consistent branch naming
```
branch-feature
```
- Feature branch workflow
```
branch-main-protected
```
- Protect main branch
```
branch-short-lived
```
- Keep branches short-lived
```
branch-delete-merged
```
- Delete merged branches
```
branch-release
```
- Release branch strategy
```
branch-workflow-strategies
```
- GitFlow vs GitHub Flow vs Trunk-Based
```
branch-monorepo
```
- Monorepo git workflows

```
branch-naming
```
- 统一分支命名
```
branch-feature
```
- 功能分支工作流
```
branch-main-protected
```
- 保护main分支
```
branch-short-lived
```
- 保持分支生命周期简短
```
branch-delete-merged
```
- 删除已合并分支
```
branch-release
```
- 发布分支策略
```
branch-workflow-strategies
```
- GitFlow、GitHub Flow与主干开发对比
```
branch-monorepo
```
- 单体仓库Git工作流

3. Pull Requests (HIGH)

3. PR（高）

```
pr-small
```
- Keep PRs small and focused
```
pr-description
```
- Write clear descriptions
```
pr-reviewers
```
- Request appropriate reviewers
```
pr-ci-pass
```
- Ensure CI passes
```
pr-squash
```
- Squash when appropriate
```
pr-draft
```
- Use draft PRs for WIP and early feedback

```
pr-small
```
- 保持PR精简且聚焦
```
pr-description
```
- 编写清晰的描述
```
pr-reviewers
```
- 邀请合适的评审人
```
pr-ci-pass
```
- 确保CI执行通过
```
pr-squash
```
- 适时压缩Commit
```
pr-draft
```
- 为进行中工作（WIP）和早期反馈使用草稿PR

4. History Management (MEDIUM)

4. 历史记录管理（中）

```
history-rebase
```
- Rebase vs merge
```
history-no-force-push
```
- Avoid force push to shared branches
```
history-clean
```
- Keep history clean
```
history-tags
```
- Use tags for releases
```
history-worktree
```
- Work on multiple branches with git worktree

```
history-rebase
```
- Rebase与Merge对比
```
history-no-force-push
```
- 避免向共享分支强制推送
```
history-clean
```
- 保持历史记录清晰
```
history-tags
```
- 使用标签标记发布版本
```
history-worktree
```
- 使用git worktree同时处理多个分支

5. Collaboration (MEDIUM)

5. 协作（中）

```
collab-code-review
```
- Effective code reviews
```
collab-conflicts
```
- Handle merge conflicts
```
collab-communication
```
- Communicate changes
```
collab-gitignore
```
- .gitignore best practices

```
collab-code-review
```
- 高效代码评审
```
collab-conflicts
```
- 处理合并冲突
```
collab-communication
```
- 同步变更信息
```
collab-gitignore
```
- .gitignore最佳实践

Essential Guidelines

核心指南

Conventional Commits

约定式Commit

undefined

undefined

Format

<body> <footer> ```

<body> <footer> ```

Types

类型

Type	Description
`feat`	New feature
`fix`	Bug fix
`docs`	Documentation only
`style`	Formatting, no code change
`refactor`	Code change, no feature/fix
`perf`	Performance improvement
`test`	Adding/updating tests
`chore`	Maintenance, dependencies
`ci`	CI/CD changes
`build`	Build system changes
`revert`	Revert previous commit

类型	描述
`feat`	新功能
`fix`	修复Bug
`docs`	仅修改文档
`style`	格式调整，无代码逻辑变更
`refactor`	代码重构，无新功能/Bug修复
`perf`	性能优化
`test`	添加/更新测试
`chore`	维护工作、依赖更新
`ci`	CI/CD配置变更
`build`	构建系统变更
`revert`	回滚之前的Commit

Examples

示例

bash

undefined

bash

undefined

✅ Good commit messages

feat(auth): add password reset functionality

fix(cart): resolve quantity update race condition

docs(readme): add installation instructions

refactor(api): extract validation into middleware

test(user): add unit tests for registration

chore(deps): update dependencies to latest versions

feat(auth): add password reset functionality

fix(cart): resolve quantity update race condition

docs(readme): add installation instructions

refactor(api): extract validation into middleware

test(user): add unit tests for registration

chore(deps): update dependencies to latest versions

With body and footer

feat(orders): implement order cancellation

Add ability for users to cancel pending orders within 24 hours. Cancelled orders trigger refund process automatically.

Closes #123 BREAKING CHANGE: Order status enum now includes 'cancelled'

feat(orders): implement order cancellation

Add ability for users to cancel pending orders within 24 hours. Cancelled orders trigger refund process automatically.

Closes #123 BREAKING CHANGE: Order status enum now includes 'cancelled'

❌ Bad commit messages

fix bug update WIP asdfasdf changes misc fixes

undefined

fix bug update WIP asdfasdf changes misc fixes

undefined

Branch Naming

分支命名

bash

undefined

bash

undefined

✅ Good branch names

feature/user-authentication feature/JIRA-123-password-reset fix/cart-total-calculation fix/issue-456-login-redirect hotfix/security-patch docs/api-documentation refactor/database-queries chore/update-dependencies

❌ Bad branch names

new-feature john-branch test fix temp asdf

undefined

new-feature john-branch test fix temp asdf

undefined

Branch Workflow

分支工作流

bash

undefined

bash

undefined

Main branches

main # Production-ready code develop # Integration branch (optional)

Supporting branches

feature/* # New features fix/* # Bug fixes hotfix/* # Production hotfixes release/* # Release preparation

Workflow

git checkout main git pull origin main git checkout -b feature/user-profile

Work on feature...

git add . git commit -m "feat(profile): add profile page"

git add . git commit -m "feat(auth): add profile page"

Keep branch updated

git fetch origin git rebase origin/main

Push and create PR

git push -u origin feature/user-profile

undefined

git push -u origin feature/user-profile

undefined

Atomic Commits

原子化Commit

bash

undefined

bash

undefined

❌ One commit doing multiple things

git commit -m "Add login, fix header, update deps"

✅ Separate commits for each change

git commit -m "feat(auth): add login page" git commit -m "fix(header): correct navigation alignment" git commit -m "chore(deps): update React to v18.2"

undefined

git commit -m "feat(auth): add login page" git commit -m "fix(header): correct navigation alignment" git commit -m "chore(deps): update React to v18.2"

undefined

Commit Frequently, Push Regularly

频繁Commit、定期推送

bash

undefined

bash

undefined

✅ Small, frequent commits

git commit -m "feat(cart): add product to cart" git commit -m "feat(cart): display cart item count" git commit -m "feat(cart): implement remove item" git commit -m "test(cart): add unit tests"

❌ One massive commit

git commit -m "feat: implement entire shopping cart"

undefined

git commit -m "feat: implement entire shopping cart"

undefined

Pull Request Best Practices

PR最佳实践

PR Title

PR标题

undefined

undefined

Format (like commit)

✅ Good PR titles

feat(auth): implement OAuth2 login fix(checkout): resolve payment processing error docs(api): add endpoint documentation

❌ Bad PR titles

Update Fix stuff WIP

undefined

Update Fix stuff WIP

undefined

PR Description Template

PR描述模板

markdown

undefined

markdown

undefined

Summary

Brief description of what this PR does.

Changes

Added user authentication endpoints
Implemented JWT token generation
Added password hashing with bcrypt

Added user authentication endpoints
Implemented JWT token generation
Added password hashing with bcrypt

Testing

Unit tests pass
Integration tests pass
Manual testing completed

Unit tests pass
Integration tests pass
Manual testing completed

Screenshots (if UI changes)

[Add screenshots here]

Related Issues

Closes #123 Related to #456

Checklist

Code follows project conventions
Self-review completed
Tests added/updated
Documentation updated

undefined

Code follows project conventions
Self-review completed
Tests added/updated
Documentation updated

undefined

Keep PRs Small

保持PR精简聚焦

undefined

undefined

✅ Focused PRs

PR #1: Add user model and migrations PR #2: Implement user registration endpoint PR #3: Add email verification PR #4: Implement login/logout

❌ Large unfocused PR

PR #1: Add entire user authentication system (2000+ lines, 50+ files)

undefined

PR #1: Add entire user authentication system (2000+ lines, 50+ files)

undefined

Rebase vs Merge

Rebase与Merge对比

bash

undefined

bash

undefined

✅ Rebase for feature branches (clean history)

git checkout feature/my-feature git fetch origin git rebase origin/main

Resolve any conflicts

git push --force-with-lease # Only your branch!

✅ Merge for integrating to main (preserve context)

git checkout main git merge --no-ff feature/my-feature

Creates merge commit, preserves branch history

❌ Never force push to shared branches

git push --force origin main # NEVER DO THIS

undefined

git push --force origin main # NEVER DO THIS

undefined

Interactive Rebase (Clean Up)

交互式Rebase（清理历史）

bash

undefined

bash

undefined

Before pushing, clean up commits

git rebase -i HEAD~5

In editor:

pick abc123 feat: add login page squash def456 fix typo squash ghi789 more fixes pick jkl012 feat: add logout

Result: clean history with meaningful commits

undefined

undefined

Handling Conflicts

处理冲突

bash

undefined

bash

undefined

During rebase

git rebase origin/main

CONFLICT in file.ts

1. Open conflicted files

2. Resolve conflicts (remove markers)

3. Stage resolved files

git add file.ts

4. Continue rebase

git rebase --continue

Or abort if needed

git rebase --abort

undefined

git rebase --abort

undefined

Git Hooks

Git钩子

bash

undefined

bash

undefined

.husky/pre-commit

#!/bin/sh npm run lint npm run test:unit

.husky/commit-msg

#!/bin/sh npx commitlint --edit $1

commitlint.config.js

module.exports = { extends: ['@commitlint/config-conventional'], };

undefined

module.exports = { extends: ['@commitlint/config-conventional'], };

undefined

Tagging Releases

版本标签标记

bash

undefined

bash

undefined

Semantic versioning tags

git tag -a v1.0.0 -m "Release version 1.0.0" git push origin v1.0.0

List tags

git tag -l "v1.*"

Tag format

v1.0.0 # Major.Minor.Patch v1.0.0-beta.1 # Pre-release v1.0.0-rc.1 # Release candidate

undefined

v1.0.0 # Major.Minor.Patch v1.0.0-beta.1 # Pre-release v1.0.0-rc.1 # Release candidate

undefined

.gitignore Best Practices

.gitignore最佳实践

gitignore

undefined

gitignore

undefined

Dependencies

node_modules/ vendor/

Build outputs

dist/ build/ .next/

Environment files

.env .env.local .env.*.local

IDE

.idea/ .vscode/ *.swp

OS files

.DS_Store Thumbs.db

Logs

*.log logs/

Test coverage

coverage/

Cache

.cache/ *.cache

undefined

.cache/ *.cache

undefined

Useful Git Commands

实用Git命令

bash

undefined

bash

undefined

View commit history

git log --oneline --graph --all

See what changed

git diff --staged git diff HEAD~1

Undo last commit (keep changes)

git reset --soft HEAD~1

Discard local changes

git checkout -- file.ts git restore file.ts # Git 2.23+

Stash changes

git stash git stash pop git stash list

Cherry-pick commit

git cherry-pick abc123

Find who changed a line

git blame file.ts

Search commits

git log --grep="fix" git log -S "functionName"

undefined

git log --grep="fix" git log -S "functionName"

undefined

Output Format

输出格式

When reviewing git practices, output findings:

[category] Description of issue or suggestion

Example:

[commit] Use imperative mood: "Add feature" not "Added feature"
[branch] Branch name 'test' should follow pattern: feature/description
[pr] PR is too large (50+ files), consider splitting

评审Git实践时，输出结果格式如下：

[类别] 问题或建议描述

示例：

[commit] 使用祈使语气：例如"Add feature"而非"Added feature"
[branch] 分支名称'test'应遵循规范：feature/描述
[pr] PR过大（50+文件），建议拆分

How to Use

使用方法

Read individual rule files for detailed explanations:

rules/commit-conventional-format.md
rules/branch-naming-convention.md
rules/pr-small-focused.md

查看单独的规则文件获取详细说明：

rules/commit-conventional-format.md
rules/branch-naming-convention.md
rules/pr-small-focused.md

References

参考资料

Git Official Documentation - Comprehensive Git documentation
Pro Git Book - The complete Pro Git book
Conventional Commits - Commit message specification
GitHub Flow - Lightweight workflow
How to Write a Git Commit Message - Commit message guide
Google Code Review Practices - Code review best practices

Git官方文档 - 全面的Git文档
Pro Git 书籍 - 完整的Pro Git指南
约定式Commit - Commit信息规范
GitHub Flow - 轻量级工作流
如何编写Git Commit信息 - Commit信息指南
Google代码评审实践 - 代码评审最佳实践

Examples from Well-Known Projects

知名项目示例

Learn from projects with excellent git practices:

Linux Kernel - Detailed commit messages and patch workflow
React - Conventional commits and thorough PR reviews
Vue.js - Clean commit history and good PR templates
TypeScript - Structured branching and clear release process
Next.js - Conventional commits and automated releases

参考具有优秀Git实践的项目：

Linux Kernel - 详细的Commit信息和补丁工作流
React - 约定式Commit和严谨的PR评审
Vue.js - 清晰的Commit历史和优质PR模板
TypeScript - 结构化分支和清晰的发布流程
Next.js - 约定式Commit和自动化发布

Configuration Examples

配置示例

Commitlint

Commitlint配置

javascript

// commitlint.config.js
module.exports = {
  extends: ['@commitlint/config-conventional'],
  rules: {
    'type-enum': [
      2,
      'always',
      ['feat', 'fix', 'docs', 'style', 'refactor', 'perf', 'test', 'chore', 'ci', 'build', 'revert']
    ],
    'subject-max-length': [2, 'always', 72],
    'body-max-line-length': [2, 'always', 100]
  }
};

javascript

// commitlint.config.js
module.exports = {
  extends: ['@commitlint/config-conventional'],
  rules: {
    'type-enum': [
      2,
      'always',
      ['feat', 'fix', 'docs', 'style', 'refactor', 'perf', 'test', 'chore', 'ci', 'build', 'revert']
    ],
    'subject-max-length': [2, 'always', 72],
    'body-max-line-length': [2, 'always', 100]
  }
};

Husky Git Hooks

Husky Git钩子配置

bash

undefined

bash

undefined

.husky/commit-msg

#!/bin/sh npx commitlint --edit $1

.husky/pre-commit

#!/bin/sh npm run lint npm test

undefined

#!/bin/sh npm run lint npm test

undefined

GitHub PR Template

GitHub PR模板

markdown

undefined

markdown

undefined

.github/PULL_REQUEST_TEMPLATE.md

Summary

Brief description of changes

Changes

List key changes
One per line

List key changes
One per line

Testing

Unit tests pass
Integration tests pass
Manual testing completed

Unit tests pass
Integration tests pass
Manual testing completed

Metadata

元数据

Skill Version: 1.2.0 Last Updated: 2026-03-08 Total Rules: 31 Categories: 5 (Commit Messages, Branching Strategy, Pull Requests, History Management, Collaboration)

Compatible With:

Git 2.0+
GitHub, GitLab, Bitbucket, Azure DevOps

Recommended Tools:

Git - Version control system
GitHub CLI - GitHub command-line tool
Commitlint - Commit message linter
Husky - Git hooks
Semantic Release - Automated versioning

技能版本: 1.2.0 最后更新: 2026-03-08 规则总数: 31 类别: 5类（Commit信息、分支策略、PR、历史记录管理、协作）

兼容环境:

Git 2.0+
GitHub、GitLab、Bitbucket、Azure DevOps

推荐工具:

Git - 版本控制系统
GitHub CLI - GitHub命令行工具
Commitlint - Commit信息校验工具
Husky - Git钩子工具
Semantic Release - 自动化版本发布工具

License

许可证

MIT License. This skill is provided as-is for educational and development purposes.

MIT许可证。本技能仅供教育和开发用途，按现状提供。

git-workflow

Original

Translation

Git Workflow

Git 工作流

When to Apply

适用场景

Rule Categories by Priority

按优先级划分的规则类别

Quick Reference

快速参考

1. Commit Messages (CRITICAL)

1. Commit 信息（关键）

2. Branching Strategy (HIGH)

2. 分支策略（高）

3. Pull Requests (HIGH)

3. PR（高）

4. History Management (MEDIUM)

4. 历史记录管理（中）

5. Collaboration (MEDIUM)

5. 协作（中）

Essential Guidelines

核心指南

Conventional Commits

约定式Commit

Format

Format

Types

类型

Examples

示例

✅ Good commit messages

✅ Good commit messages

With body and footer

With body and footer

❌ Bad commit messages

❌ Bad commit messages

Branch Naming

分支命名

✅ Good branch names

✅ Good branch names

❌ Bad branch names

❌ Bad branch names

Branch Workflow

分支工作流

Main branches

Main branches

Supporting branches

Supporting branches

Workflow

Workflow

Work on feature...

Work on feature...

Keep branch updated

Keep branch updated

Push and create PR

Push and create PR

Atomic Commits

原子化Commit

❌ One commit doing multiple things

❌ One commit doing multiple things

✅ Separate commits for each change

✅ Separate commits for each change

Commit Frequently, Push Regularly

频繁Commit、定期推送

✅ Small, frequent commits

✅ Small, frequent commits

❌ One massive commit

❌ One massive commit

Pull Request Best Practices

PR最佳实践

PR Title

PR标题

Format (like commit)

Format (like commit)

✅ Good PR titles

✅ Good PR titles

❌ Bad PR titles

❌ Bad PR titles

PR Description Template