git-workflow

name	git-workflow
description	Git workflow patterns for branching, commit conventions, merge vs rebase, and conflict resolution. Use when setting up branching strategies, writing commit messages, resolving merge conflicts, or standardizing git workflows.
origin	MCC

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 Strategy Summary

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)

git checkout main
git merge feature/user-auth

Use when: merging feature branches into main, preserving exact history, multiple contributors on the branch, or the branch has been pushed.

Rebase (Linear History)

git checkout feature/user-auth
git rebase main

Use when: updating your local feature branch with latest main, you want linear history, the branch is local-only, or you are the sole contributor.

Rebase Workflow

git checkout feature/user-auth
git fetch origin
git rebase origin/main

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

When NOT to Rebase

• Branches that have been pushed to a shared repository
• Branches other people have based work on
• Protected branches (main, develop)
• Already merged branches

Anti-Patterns

# BAD: Committing directly to main
# BAD: Committing secrets (.env with API keys)
# BAD: Giant PRs (1000+ lines)
# BAD: "Update" commit messages
# BAD: Rewriting public history (git push --force origin main)
# BAD: Long-lived feature branches (weeks/months)
# BAD: Committing generated files (dist/, node_modules/)

# GOOD: Use feature branches and PRs
# GOOD: Add secrets to .gitignore, use environment variables
# GOOD: Break into smaller, focused PRs
# GOOD: Descriptive messages with conventional commits
# GOOD: Use revert for public branches
# GOOD: Keep branches short (days), rebase frequently
# GOOD: Add generated files to .gitignore

Quick Reference

Task	Command
Create branch	git checkout -b feature/name
Switch branch	git checkout branch-name
Delete branch	git branch -d branch-name
Merge branch	git merge branch-name
Rebase branch	git rebase main
View history	git log --oneline --graph
View changes	git diff
Stage changes	git add . or git add -p
Commit	git commit -m "message"
Push	git push origin branch-name
Pull	git pull origin branch-name
Stash	git stash push -m "message"
Undo last commit	git reset --soft HEAD~1
Revert commit	git revert HEAD

Reference Files

• branching-and-releases.md — Detailed branching strategies (GitHub Flow, trunk-based, GitFlow), branch naming, cleanup, stash workflow, semantic versioning, and release management
• pr-and-collaboration.md — PR templates, code review checklists, conflict resolution, common workflows, undoing mistakes, Git hooks, configuration, aliases, and gitignore patterns