
About
Git workflow patterns including branching strategies, commit conventions, merge vs rebase, conflict resolution, and collaborative development best practices for teams of all sizes.
name: git-workflow description: Git workflow patterns including branching strategies, commit conventions, merge vs rebase, conflict resolution, and collaborative development best practices for teams of all sizes. origin: ECC
Git Workflow Patterns
Best practices for Git version control, branching strategies, and collaborative development.
When to Activate
- Setting up Git workflow for a new project
- Deciding on branching strategy (GitFlow, trunk-based, GitHub flow)
- Writing commit messages and PR descriptions
- Resolving merge conflicts
- Managing releases and version tags
- Onboarding new team members to Git practices
Branching Strategies
GitHub Flow (Simple, Recommended for Most)
Best for continuous deployment and small-to-medium teams.
main (protected, always deployable)
│
├── feature/user-auth → PR → merge to main
├── feature/payment-flow → PR → merge to main
└── fix/login-bug → PR → merge to main
Rules:
mainis always deployable- Create feature branches from
main - Open Pull Request when ready for review
- After approval and CI passes, merge to
main - Deploy immediately after merge
Trunk-Based Development (High-Velocity Teams)
Best for teams with strong CI/CD and feature flags.
main (trunk)
│
├── short-lived feature (1-2 days max)
├── short-lived feature
└── short-lived feature
Rules:
- Everyone commits to
mainor very short-lived branches - Feature flags hide incomplete work
- CI must pass before merge
- Deploy multiple times per day
GitFlow (Complex, Release-Cycle Driven)
Best for scheduled releases and enterprise projects.
main (production releases)
│
└── develop (integration branch)
│
├── feature/user-auth
├── feature/payment
│
├── release/1.0.0 → merge to main and develop
│
└── hotfix/critical → merge to main and develop
Rules:
maincontains production-ready code onlydevelopis the integration branch- Feature branches from
develop, merge back todevelop - Release branches from
develop, merge tomainanddevelop - Hotfix branches from
main, merge to bothmainanddevelop
When to Use Which
| Strategy | Team Size | Release Cadence | Best For | |----------|-----------|-----------------|----------| | GitHub Flow | Any | Continuous | SaaS, web apps, startups | | Trunk-Based | 5+ experienced | Multiple/day | High-velocity teams, feature flags | | GitFlow | 10+ | Scheduled | Enterprise, regulated industries |
Commit Messages
Conventional Commits Format
<type>(<scope>): <subject>
[optional body]
[optional footer(s)]
Types
| Type | Use For | Example |
|------|---------|---------|
| feat | New feature | feat(auth): add OAuth2 login |
| fix | Bug fix | fix(api): handle null response in user endpoint |
| docs | Documentation | docs(readme): update installation instructions |
| style | Formatting, no code change | style: fix indentation in login component |
| refactor | Code refactoring | refactor(db): extract connection pool to module |
| test | Adding/updating tests | test(auth): add unit tests for token validation |
| chore | Maintenance tasks | chore(deps): update dependencies |
| perf | Performance improvement | perf(query): add index to users table |
| ci | CI/CD changes | ci: add PostgreSQL service to test workflow |
| revert | Revert previous commit | revert: revert "feat(auth): add OAuth2 login" |
Good vs Bad Examples
# BAD: Vague, no context
git commit -m "fixed stuff"
git commit -m "updates"
git commit -m "WIP"
# GOOD: Clear, specific, explains why
git commit -m "fix(api): retry requests on 503 Service Unavailable
The external API occasionally returns 503 errors during peak hours.
Added exponential backoff retry logic with max 3 attempts.
Closes #123"
Commit Message Template
Create .gitmessage in repo root:
# <type>(<scope>): <subject>
# # Types: feat, fix, docs, style, refactor, test, chore, perf, ci, revert
# Scope: api, ui, db, auth, etc.
# Subject: imperative mood, no period, max 50 chars
#
# [optional body] - explain why, not what
# [optional footer] - Breaking changes, closes #issue
Enable with: git config commit.template .gitmessage
Merge vs Rebase
Merge (Preserves History)
# Creates a merge commit
git checkout main
git merge feature/user-auth
# Result:
# * merge commit
# |\
# | * feature commits
# |/
# * main commits
Use when:
- Merging feature branches into
main - You want to preserve exact history
- Multiple people worked on the branch
- The branch has been pushed and others may have based work on it
Rebase (Linear History)
# Rewrites feature commits onto target branch
git checkout feature/user-auth
git rebase main
# Result:
# * feature commits (rewritten)
# * main commits
Use when:
- Updating your local feature branc
