Git workflow guide

Git Workflow Guide

This skill provides guidance on Git branching strategies, branch naming conventions, and merge operations.

Quick Reference

Workflow Strategy Selection

Deployment Frequency	Recommended Strategy
Multiple times/day	Trunk-Based Development
Weekly to bi-weekly	GitHub Flow
Monthly or longer	GitFlow

Branch Naming Convention

<type>/<short-description>

Type	Usage	Example
feature/	New functionality	feature/oauth-login
fix/ or bugfix/	Bug fixes	fix/memory-leak
hotfix/	Urgent production fixes	hotfix/security-patch
refactor/	Code refactoring	refactor/extract-service
docs/	Documentation only	docs/api-reference
test/	Test additions	test/integration-tests
chore/	Maintenance tasks	chore/update-dependencies
release/	Release preparation	release/v1.2.0

Naming Rules

1. Use lowercase | 使用小寫
2. Use hyphens for spaces | 使用連字號分隔單詞
3. Be descriptive but concise | 具描述性但簡潔

Detailed Guidelines

For complete standards, see:

• Git Workflow Strategies
• Branch Naming Reference

Pre-branch Checklist

Before creating a new branch:

1. Check for unmerged branches

   git branch --no-merged main
   

2. Sync latest code

   git checkout main
   git pull origin main
   

3. Verify tests pass

   npm test  # or your project's test command
   

4. Create branch with proper naming

   git checkout -b feature/description
   

Merge Strategy Quick Guide

Strategy	When to Use
Merge Commit (--no-ff)	Long-lived features, GitFlow releases
Squash Merge	Feature branches, clean history
Rebase + FF	Trunk-Based, short-lived branches

Examples

Creating a Feature Branch

# Good
git checkout -b feature/user-authentication
git checkout -b fix/null-pointer-in-payment
git checkout -b hotfix/critical-data-loss

# Bad
git checkout -b 123              # Not descriptive
git checkout -b Fix-Bug          # Not lowercase
git checkout -b myFeature        # No type prefix

Merge Workflow (GitHub Flow)

# 1. Create branch from main
git checkout main
git pull origin main
git checkout -b feature/user-profile

# 2. Make changes and commit
git add .
git commit -m "feat(profile): add avatar upload"
git push -u origin feature/user-profile

# 3. Create PR and merge via GitHub/GitLab UI

# 4. Delete branch after merge
git checkout main
git pull origin main
git branch -d feature/user-profile

Handling Merge Conflicts

# 1. Update your branch with main
git checkout feature/my-feature
git fetch origin
git merge origin/main

# 2. Resolve conflicts in files
# <<<<<<< HEAD
# Your changes
# =======
# Incoming changes
# >>>>>>> origin/main

# 3. Stage resolved files
git add resolved-file.js

# 4. Complete merge
git commit -m "chore: resolve merge conflicts with main"

# 5. Test and push
npm test
git push origin feature/my-feature

---

Configuration Detection

This skill supports project-specific workflow configuration.

Detection Order

1. Check CONTRIBUTING.md for "Git Workflow" or "Branching Strategy" section
2. If found, use the specified strategy (GitFlow / GitHub Flow / Trunk-Based)
3. If not found, default to GitHub Flow for simplicity

First-Time Setup

If no configuration found:

1. Ask the user: "This project hasn't configured a Git workflow strategy. Which would you prefer? (GitFlow / GitHub Flow / Trunk-Based)"
2. After selection, suggest documenting in CONTRIBUTING.md:

## Git Workflow

### Branching Strategy
This project uses **[chosen option]**.

### Branch Naming
Format: `<type>/<description>`
Example: `feature/oauth-login`, `fix/memory-leak`

### Merge Strategy
- Feature branches: **[Squash / Merge commit / Rebase]**

---

License: CC BY 4.0 | Source: universal-dev-standards