playbooks

home / skills / enoch-robinson / agent-skill-collection / git-workflow

git-workflow skill

/skills/development/git-workflow

This skill helps you manage Git branches, commits, and conflicts following conventional workflows to ensure collaborative, scalable version control.

npx playbooks add skill enoch-robinson/agent-skill-collection --skill git-workflow

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
1.8 KB
---
name: git-workflow
description: Git 工作流和版本控制最佳实践。当用户需要管理 Git 分支、编写提交信息、解决合并冲突、或遵循 Git 工作流规范时使用此技能。
---

# Git Workflow

提供专业的 Git 版本控制工作流指导，确保团队协作高效有序。

## 分支策略

### 主要分支
- `main/master`：生产环境代码，始终保持可部署状态
- `develop`：开发主分支，集成最新功能

### 功能分支命名
```
feature/[issue-id]-简短描述    # 新功能
bugfix/[issue-id]-简短描述     # Bug修复
hotfix/[issue-id]-简短描述     # 紧急修复
refactor/简短描述              # 重构
docs/简短描述                  # 文档更新
```

## Commit 规范 (Conventional Commits)

```
<type>(<scope>): <subject>

<body>

<footer>
```

### Type类型
| Type | 描述 |
|------|------|
| feat | 新功能 |
| fix | Bug 修复 |
| docs | 文档更新 |
| style | 代码格式（不影响逻辑） |
| refactor | 重构（非新功能/修复） |
| perf | 性能优化 |
| test | 测试相关 |
| chore | 构建/工具变更 |

### 示例
```
feat(auth): 添加 OAuth2.0 登录支持

- 集成 Google OAuth 认证
- 添加 token刷新机制
- 更新用户模型

Closes #123
```

## 常用工作流

### 开始新功能
```bash
git checkout develop
git pull origin develop
git checkout -b feature/123-user-auth
```

### 提交变更
```bash
git add .
git commit -m "feat(auth): 实现用户登录功能"
git push origin feature/123-user-auth
```

### 合并前更新
```bash
git fetch origin
git rebase origin/develop
# 解决冲突后
git push --force-with-lease
```

##冲突解决原则

1. **理解双方变更**：先了解冲突原因
2. **保留正确逻辑**：不要简单地选择一方
3. **测试验证**：解决后必须测试
4. **及时沟通**：复杂冲突与相关人员确认

Overview

This skill provides practical Git workflow and version control best practices to keep team collaboration efficient and codebases stable. It covers branch strategies, commit message conventions, common workflows, rebasing, and conflict resolution principles. Use it to standardize Git usage across projects and reduce integration friction.

How this skill works

It inspects typical Git actions and guides you through branching, committing, updating, and merging steps with concrete commands and naming rules. It enforces Conventional Commits-style messages and recommends branch naming patterns for features, fixes, hotfixes, refactors, and docs. It also outlines safe rebase procedures and clear conflict-resolution steps to minimize mistakes and preserve history.

When to use it

  • Starting a new feature or hotfix to create the correct branch and naming
  • Writing commits to follow a clear Conventional Commits format
  • Preparing a branch for merge by rebasing or updating from the integration branch
  • Resolving merge conflicts while preserving correct logic and tests
  • Establishing team-wide Git rules and onboarding new contributors

Best practices

  • Keep main/master deployable; use develop (or similar) as the integration branch
  • Use descriptive branch names like feature/123-short-desc or bugfix/45-short-desc
  • Write commits in Conventional Commits format: type(scope): subject and include body/footer for details
  • Rebase feature branches onto develop before merging to keep history linear and resolve conflicts early
  • When resolving conflicts, understand both sides, preserve correct logic, test thoroughly, and communicate with authors
  • Push rebased branches with git push --force-with-lease to avoid overwriting others' work

Example use cases

  • Implementing a new user-auth feature: create feature/123-user-auth, commit with feat(auth):, rebase onto develop, open PR
  • Fixing a production bug: branch hotfix/456-critical-fix, commit fix(scope):, test and merge to main then backport to develop
  • Refactoring a module: use refactor/module-name branch, break changes into small commits, document intent in commit body
  • Updating documentation: use docs/update-installation branch and commit with docs(scope):
  • Merging a long-lived feature: frequently rebase onto develop, resolve conflicts with involved teammates, then open a clean PR

FAQ

When should I use rebase vs merge?

Rebase keeps a linear history and is good for feature branches before merging; merge preserves the exact integration history and is fine for shared branches or when you want a merge commit record.

How to write a good commit message?

Use type(scope): short subject, add a body explaining what and why, and include a footer for related issue references (e.g., Closes #123). Keep subjects under ~72 chars.