---

name: git-workflow-guide description: | Guide Git branching strategies, branch naming, and merge operations. Use when: creating branches, merging, pull requests, Git workflow questions. Keywords: branch, merge, PR, pull request, GitFlow, GitHub Flow, 分支, 合併, 工作流程.

Git Workflow Guide

Language: English | 繁體中文

Version: 1.0.0 Last Updated: 2025-12-24 Applicability: Claude Code Skills

---

Purpose

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

Quick Reference

Workflow Strategy Selection

Branch Naming Convention

Copy<type>/<short-description>

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

AI-Optimized Format (Token-Efficient)

For AI assistants, use the YAML format files for reduced token usage:

• Base standard: ai/standards/git-workflow.ai.yaml
• Workflow options:
  • GitHub Flow: ai/options/git-workflow/github-flow.ai.yaml
  • GitFlow: ai/options/git-workflow/gitflow.ai.yaml
  • Trunk-Based: ai/options/git-workflow/trunk-based.ai.yaml
• Merge strategy options:
  • Squash Merge: ai/options/git-workflow/squash-merge.ai.yaml
  • Merge Commit: ai/options/git-workflow/merge-commit.ai.yaml
  • Rebase + FF: ai/options/git-workflow/rebase-ff.ai.yaml

Pre-branch Checklist

Before creating a new branch:

1. Check for unmerged branches

   Copygit branch --no-merged main
   

2. Sync latest code

   Copygit checkout main
   git pull origin main
   

3. Verify tests pass

   Copynpm test  # or your project's test command
   

4. Create branch with proper naming

   Copygit checkout -b feature/description
   

Merge Strategy Quick Guide

Examples

Creating a Feature Branch

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

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

Copy# 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:

Copy## 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]**

---

Related Standards

• Git Workflow
• Commit Message Guide
• Checkin Standards

---

Version History

---

License

This skill is released under CC BY 4.0.

Source: universal-dev-standards