/git-workflow

name: git-workflow
description: Git workflow patterns including branching strategies, commit conventions, keeping history clean and readable, tidying local commits before merging, merge vs rebase, conflict resolution, and collaborative development best practices for teams of all sizes. Use when choosing a branching strategy, writing commit conventions, cleaning up history before a pull request, deciding merge versus rebase, or resolving conflicts.
metadata:
  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:**

• `main` is 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 `main` or 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:**

• `main` contains production-ready code only
• `develop` is the integration branch
• Feature branches from `develop`, merge back to `develop`
• Release branches from `develop`, merge to `main` and `develop`
• Hotfix branches from `main`, merge to both `main` and `develop`

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 branch with latest `main`
• You want a linear, clean history
• The branch is local-only (not pushed)
• You're the only one working on the branch

Rebase Workflow

# Update feature branch with latest main (before PR)
git checkout feature/user-auth
git fetch origin
git rebase origin/main

# Fix any conflicts
# Tests should still pass

# Force push (only if you're the only contributor)
git push --force-with-lease origin feature/user-auth

When NOT to Rebase

# NEVER rebase branches that:
- Have been pushed to a shared repository
- Other people have based work on
- Are protected branches (main, develop)
- Are already merged

# Why: Rebase rewrites history, breaking others' work

Pull Request Workflow

PR Title For