Git工作流最佳实践指南：提交规范、分支策略与协作流程

git-workflow by asyrafhussin/agent-skills

79 周安装量

18 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/asyrafhussin/agent-skills --skill git-workflow

团队协作编程最佳实践版本控制

🇨🇳中文介绍

Git 工作流

Git 最佳实践、提交规范、分支策略和拉取请求工作流。维护清晰、有用的 Git 历史的指南。

何时应用

在以下情况下参考这些指南：

编写提交信息时
创建分支时
设置 Git 工作流时
审查拉取请求时
维护 Git 历史时

按优先级排序的规则类别

优先级	类别	影响	前缀
1	提交信息	关键	`commit-`
2	分支策略	高	`branch-`
3	拉取请求	高	`pr-`

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

1. 提交信息（关键）

commit-conventional - 使用约定式提交
commit-atomic - 原子提交（一个逻辑变更）
commit-present-tense - 使用祈使句现在时
commit-meaningful - 描述性、有意义的信息
commit-body - 为复杂变更添加正文
commit-references - 引用问题/工单
commit-git-hooks - 使用 Husky + commitlint 强制执行标准

2. 分支策略（高）

branch-naming - 一致的分支命名
branch-feature - 功能分支工作流
branch-main-protected - 保护主分支
branch-short-lived - 保持分支短命
branch-delete-merged - 删除已合并的分支
branch-release - 发布分支策略
branch-workflow-strategies - GitFlow vs GitHub Flow vs 主干开发
branch-monorepo - 单体仓库 Git 工作流

3. 拉取请求（高）

pr-small - 保持 PR 小而专注
pr-description - 编写清晰的描述
pr-reviewers - 请求合适的审查者
pr-ci-pass - 确保 CI 通过
pr-squash - 在适当时进行压缩
pr-draft - 对进行中的工作和早期反馈使用草稿 PR

4. 历史管理（中）

history-rebase - 变基 vs 合并
history-no-force-push - 避免强制推送到共享分支
history-clean - 保持历史整洁
history-tags - 为发布使用标签
history-worktree - 使用 git worktree 处理多个分支

collab-code-review - 有效的代码审查
collab-conflicts - 处理合并冲突
collab-communication - 沟通变更
collab-gitignore - .gitignore 最佳实践

# 格式
<类型>(<作用域>): <主题>

<正文>

<页脚>

类型	描述
`feat`	新功能
`fix`	错误修复
`docs`	仅文档
`style`	格式化，无代码变更
`refactor`	代码重构，无功能/修复
`perf`	性能改进
`test`	添加/更新测试
`chore`	维护、依赖项
`ci`	CI/CD 变更
`build`	构建系统变更
`revert`	回滚之前的提交

# ✅ 好的提交信息
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(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'

# ❌ 差的提交信息
fix bug
update
WIP
asdfasdf
changes
misc fixes

# ✅ 好的分支名称
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

# ❌ 差的分支名称
new-feature
john-branch
test
fix
temp
asdf

# 主分支
main          # 生产就绪代码
develop       # 集成分支（可选）

# 支持分支
feature/*     # 新功能
fix/*         # 错误修复
hotfix/*      # 生产热修复
release/*     # 发布准备

# 工作流
git checkout main
git pull origin main
git checkout -b feature/user-profile

# 在功能上工作...
git add .
git commit -m "feat(profile): add profile page"

# 保持分支更新
git fetch origin
git rebase origin/main

# 推送并创建 PR
git push -u origin feature/user-profile

# ❌ 一个提交做多件事
git commit -m "Add login, fix header, update deps"

# ✅ 为每个变更单独提交
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"

频繁提交，定期推送

# ✅ 小而频繁的提交
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"

# ❌ 一个巨大的提交
git commit -m "feat: implement entire shopping cart"

拉取请求最佳实践

# 格式（类似提交）
<类型>(<作用域>): <描述>

# ✅ 好的 PR 标题
feat(auth): implement OAuth2 login
fix(checkout): resolve payment processing error
docs(api): add endpoint documentation

# ❌ 差的 PR 标题
Update
Fix stuff
WIP

## 摘要
简要描述此 PR 的作用。

## 变更
- 添加了用户认证端点
- 实现了 JWT 令牌生成
- 添加了使用 bcrypt 的密码哈希

## 测试
- [ ] 单元测试通过
- [ ] 集成测试通过
- [ ] 手动测试完成

## 截图（如果是 UI 变更）
[在此处添加截图]

## 相关问题
Closes #123
Related to #456

## 检查清单
- [ ] 代码遵循项目约定
- [ ] 已完成自审
- [ ] 已添加/更新测试
- [ ] 已更新文档

# ✅ 专注的 PR
PR #1: 添加用户模型和迁移
PR #2: 实现用户注册端点
PR #3: 添加邮箱验证
PR #4: 实现登录/登出

# ❌ 庞大且不专注的 PR
PR #1: 添加整个用户认证系统
       (2000+ 行，50+ 文件)

# ✅ 对功能分支使用变基（干净的历史）
git checkout feature/my-feature
git fetch origin
git rebase origin/main
# 解决任何冲突
git push --force-with-lease  # 仅限你的分支！

# ✅ 对集成到主分支使用合并（保留上下文）
git checkout main
git merge --no-ff feature/my-feature
# 创建合并提交，保留分支历史

# ❌ 切勿强制推送到共享分支
git push --force origin main  # 永远不要这样做

交互式变基（清理）

# 推送前，清理提交
git rebase -i HEAD~5

# 在编辑器中：
pick abc123 feat: add login page
squash def456 fix typo
squash ghi789 more fixes
pick jkl012 feat: add logout

# 结果：具有有意义提交的干净历史

# 在变基期间
git rebase origin/main
# 文件 file.ts 中存在冲突

# 1. 打开冲突文件
# 2. 解决冲突（移除标记）
# 3. 暂存已解决的文件
git add file.ts

# 4. 继续变基
git rebase --continue

# 或在需要时中止
git rebase --abort

# .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'],
};

# 语义化版本标记
git tag -a v1.0.0 -m "Release version 1.0.0"
git push origin v1.0.0

# 列出标签
git tag -l "v1.*"

# 标签格式
v1.0.0    # 主版本.次版本.修订号
v1.0.0-beta.1  # 预发布
v1.0.0-rc.1    # 发布候选

.gitignore 最佳实践

# 依赖项
node_modules/
vendor/

# 构建输出
dist/
build/
.next/

# 环境文件
.env
.env.local
.env.*.local

# IDE
.idea/
.vscode/
*.swp

# 操作系统文件
.DS_Store
Thumbs.db

# 日志
*.log
logs/

# 测试覆盖率
coverage/

# 缓存
.cache/
*.cache

有用的 Git 命令

# 查看提交历史
git log --oneline --graph --all

# 查看变更内容
git diff --staged
git diff HEAD~1

# 撤销最后一次提交（保留更改）
git reset --soft HEAD~1

# 丢弃本地更改
git checkout -- file.ts
git restore file.ts  # Git 2.23+

# 暂存更改
git stash
git stash pop
git stash list

# 拣选提交
git cherry-pick abc123

# 查找谁更改了一行
git blame file.ts

# 搜索提交
git log --grep="fix"
git log -S "functionName"

审查 Git 实践时，输出发现：

[类别] 问题或建议的描述

[commit] 使用祈使语气："Add feature" 而非 "Added feature"
[branch] 分支名称 'test' 应遵循模式：feature/description
[pr] PR 太大（50+ 文件），请考虑拆分

阅读单独的规则文件以获取详细说明：

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

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

向具有优秀 Git 实践的项目学习：

Linux 内核 - 详细的提交信息和补丁工作流
React - 约定式提交和彻底的 PR 审查
Vue.js - 干净的提交历史和良好的 PR 模板
TypeScript - 结构化的分支和清晰的发布流程
Next.js - 约定式提交和自动化发布

// 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/commit-msg
#!/bin/sh
npx commitlint --edit $1

# .husky/pre-commit
#!/bin/sh
npm run lint
npm test

# .github/PULL_REQUEST_TEMPLATE.md
## 摘要
变更的简要描述

## 变更
- 列出关键变更
- 每行一个

## 测试
- [ ] 单元测试通过
- [ ] 集成测试通过
- [ ] 手动测试完成

## 相关
Closes #issue-number

技能版本： 1.2.0 最后更新： 2026-03-08 总规则数： 31 类别： 5（提交信息、分支策略、拉取请求、历史管理、协作）

Git 2.0+
GitHub, GitLab, Bitbucket, Azure DevOps

Git - 版本控制系统
GitHub CLI - GitHub 命令行工具
Commitlint - 提交信息检查器
Husky - Git 钩子
Semantic Release - 自动化版本管理

MIT 许可证。本技能按原样提供，用于教育和开发目的。

🇺🇸English

Git Workflow

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

When to Apply

Reference these guidelines when:

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

Rule Categories by Priority

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-`

Quick Reference

1. Commit Messages (CRITICAL)

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

2. Branching Strategy (HIGH)

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

3. Pull Requests (HIGH)

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

4. History Management (MEDIUM)

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

5. Collaboration (MEDIUM)

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

Essential Guidelines

Conventional Commits

# Format
<type>(<scope>): <subject>

<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

Examples

# ✅ 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

# 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'

# ❌ Bad commit messages
fix bug
update
WIP
asdfasdf
changes
misc fixes

Branch Naming

# ✅ 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

Branch Workflow

# 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"

# Keep branch updated
git fetch origin
git rebase origin/main

# Push and create PR
git push -u origin feature/user-profile

Atomic Commits

# ❌ 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"

Commit Frequently, Push Regularly

# ✅ 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"

Pull Request Best Practices

PR Title

# Format (like commit)
<type>(<scope>): <description>

# ✅ 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

PR Description Template

## Summary
Brief description of what this PR does.

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

## Testing
- [ ] 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

Keep PRs Small

# ✅ 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)

Rebase vs Merge

# ✅ 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

Interactive Rebase (Clean Up)

# 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

Handling Conflicts

# 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

Git Hooks

# .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'],
};

Tagging Releases

# 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

.gitignore Best Practices

# 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

Useful Git Commands

# 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"

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

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

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

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

Configuration Examples

Commitlint

// 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/commit-msg
#!/bin/sh
npx commitlint --edit $1

# .husky/pre-commit
#!/bin/sh
npm run lint
npm test

GitHub PR Template

# .github/PULL_REQUEST_TEMPLATE.md
## Summary
Brief description of changes

## Changes
- List key changes
- One per line

## Testing
- [ ] Unit tests pass
- [ ] Integration tests pass
- [ ] Manual testing completed

## Related
Closes #issue-number

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

License

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

Weekly Installs

Repository

asyrafhussin/ag…t-skills

GitHub Stars

First Seen

Jan 24, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykWarn

Installed on

gemini-cli43

opencode41

codex39

cursor39

claude-code37

github-copilot36

利益相关方更新生成器 | 自动化项目沟通工具 | 支持多受众定制

493 周安装

Git工作流最佳实践指南：提交规范、分支策略与协作流程

🇨🇳中文介绍

Git 工作流

何时应用

按优先级排序的规则类别

相关 Skills

快速参考

1. 提交信息（关键）

2. 分支策略（高）

3. 拉取请求（高）

4. 历史管理（中）

5. 协作（中）

基本指南

约定式提交

类型

示例

分支命名

分支工作流

原子提交

频繁提交，定期推送

拉取请求最佳实践

PR 标题

PR 描述模板

保持 PR 小巧

变基 vs 合并

交互式变基（清理）

处理冲突

Git 钩子

标记发布

.gitignore 最佳实践

有用的 Git 命令

输出格式

如何使用

参考资料

知名项目示例

配置示例

Commitlint

Husky Git 钩子

GitHub PR 模板

元数据

许可证

🇺🇸English

Git Workflow

When to Apply

Rule Categories by Priority

Quick Reference

1. Commit Messages (CRITICAL)

2. Branching Strategy (HIGH)

3. Pull Requests (HIGH)

4. History Management (MEDIUM)

5. Collaboration (MEDIUM)

Essential Guidelines

Conventional Commits

Types

Examples

Branch Naming

Branch Workflow

Atomic Commits

Commit Frequently, Push Regularly

Pull Request Best Practices

PR Title

PR Description Template

Keep PRs Small

Rebase vs Merge

Interactive Rebase (Clean Up)

Handling Conflicts

Git Hooks

Tagging Releases

.gitignore Best Practices

Useful Git Commands

Output Format

How to Use

References

Examples from Well-Known Projects

Configuration Examples

Commitlint

Husky Git Hooks

GitHub PR Template

Metadata

License