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 Format

<type>(<scope>): <description>
Examples:
feat(auth): add SSO support for enterprise users
fix(api): resolve race condition in order processing
docs(api): add OpenAPI specification for v2 endpoints

PR Description Template

## What
Brief description of what this PR does.
Why
Explain the motivation and context.
How
Key implementation details worth highlighting.
Testing
[ ] Unit tests added/updated
[ ] Integration tests added/updated
[ ] Manual testing performed

Screenshots (if applicable)
Before/after screenshots for UI changes.
Checklist
[ ] Code follows project style guidelines
[ ] Self-review completed
[ ] Comments added for complex logic
[ ] Documentation updated
[ ] No new warnings introduced
[ ] Tests pass locally
[ ] Related issues linked

Closes #123

Code Review Checklist

For Reviewers:

• [ ] Does the code solve the stated problem?
• [ ] Are there any edge cases not handled?
• [ ] Is the code readable and maintainable?
• [ ] Are there sufficient tests?
• [ ] Are there security concerns?
• [ ] Is the commit history clean (squashed if needed)?

• [ ] Self-review completed before requesting review
• [ ] CI passes (tests, lint, typecheck)
• [ ] PR size is reasonable (<500 lines ideal)
• [ ] Related to a single feature/fix
• [ ] Description clearly explains the change

Conflict Resolution

Identify Conflicts

# Check for conflicts before merge
git checkout main
git merge feature/user-auth --no-commit --no-ff
If conflicts, Git will show:
CONFLICT (content): Merge conflict in src/auth/login.ts
Automatic merge failed; fix conflicts and then commit the result.

Resolve Conflicts

# See conflicted files
git status
View conflict markers in file
<<<<<<< HEAD
content from main
=======
content from feature branch
>>>>>>> feature/user-auth
Option 1: Manual resolution
Edit file, remove markers, keep correct content
Option 2: Use merge tool
git mergetool
Option 3: Accept one side
git checkout --ours src/auth/login.ts    # Keep main version
git checkout --theirs src/auth/login.ts  # Keep feature version
After resolving, stage and commit
git add src/auth/login.ts
git commit

Conflict Prevention Strategies

# 1. Keep feature branches small and short-lived
2. Rebase frequently onto main
git checkout feature/user-auth
git fetch origin
git rebase origin/main
3. Communicate with team about touching shared files
4. Use feature flags instead of long-lived branches
5. Review and merge PRs promptly

Branch Management

Naming Conventions

# Feature branches
feature/user-authentication
feature/JIRA-123-payment-integration
Bug fixes
fix/login-redirect-loop
fix/456-null-pointer-exception
Hotfixes (production issues)
hotfix/critical-security-patch
hotfix/database-connection-leak
Releases
release/1.2.0
release/2024-01-hotfix
Experiments/POCs
experiment/new-caching-strategy
poc/graphql-migration

Branch Cleanup

# Delete local branches that are merged
git branch --merged main | grep -v "^\*\|main" | xargs -n 1 git branch -d
Delete remote-tracking references for deleted remote branches
git fetch -p
Delete local branch
git branch -d feature/user-auth  # Safe delete (only if merged)
git branch -D feature/user-auth  # Force delete
Delete remote branch
git push origin --delete feature/user-auth

Stash Workflow

# Save work in progress
git stash push -m "WIP: user authentication"
List stashes
git stash list
Apply most recent stash
git stash pop
Apply specific stash
git stash apply stash@{2}
Drop stash
git stash drop stash@{0}

Release Management

Semantic Versioning

MAJOR.MINOR.PATCH
MAJOR: Breaking changes
MINOR: New features, backward compatible
PATCH: Bug fixes, backward compatible
Examples:
1.0.0 → 1.0.1 (patch: bug fix)
1.0.1 → 1.1.0 (minor: new feature)
1.1.0 → 2.0.0 (major: breaking change)

Creating Releases

# Create annotated tag
git tag -a v1.2.0 -m "Release v1.2.0
Features:
Add user authentication
Implement password reset

Fixes:
Resolve login redirect issue

Breaking Changes:
None"

Push tag to remote
git push origin v1.2.0
List tags
git tag -l
Delete tag
git tag -d v1.2.0
git push origin --delete v1.2.0

Changelog Generation

# Generate changelog from commits
git log v1.1.0..v1.2.0 --oneline --no-merges
Or use conventional-changelog
npx conventional-changelog -i CHANGELOG.md -s

Git Configuration

Essential Configs

# User identity
git config --global user.name "Your Name"
git config --global user.email "[email protected]"
Default branch name
git config --global init.defaultBranch main
Pull behavior (rebase instead of merge)
git config --global pull.rebase true
Push behavior (push current branch only)
git config --global push.default current
Auto-correct typos
git config --global help.autocorrect 1
Better diff algorithm
git config --global diff.algorithm histogram
Color output
git config --global color.ui auto

Useful Aliases

# Add to ~/.gitconfig
[alias]
    co = checkout
    br = branch
    ci = commit
    st = status
    unstage = reset HEAD --
    last = log -1 HEAD
    visual = log --oneline --graph --all
    amend = commit --amend --no-edit
    wip = commit -m "WIP"
    undo = reset --soft HEAD~1
    contributors = shortlog -sn

Gitignore Patterns

# Dependencies
node_modules/
vendor/
Build outputs
dist/
build/
*.o
*.exe
Environment files
.env
.env.local
.env.*.local
IDE
.idea/
.vscode/
*.swp
*.swo
OS files
.DS_Store
Thumbs.db
Logs
*.log
logs/
Test coverage
coverage/
Cache
.cache/
*.tsbuildinfo

Common Workflows

Starting a New Feature

# 1. Update main branch
git checkout main
git pull origin main
2. Create feature branch
git checkout -b feature/user-auth
3. Make changes and commit
git add .
git commit -m "feat(auth): implement OAuth2 login"
4. Push to remote
git push -u origin feature/user-auth
5. Create Pull Request on GitHub/GitLab

Updating a PR with New Changes

# 1. Make additional changes
git add .
git commit -m "feat(auth): add error handling"
2. Push updates
git push origin feature/user-auth

Syncing Fork with Upstream

# 1. Add upstream remote (once)
git remote add upstream https://github.com/original/repo.git
2. Fetch upstream
git fetch upstream
3. Merge upstream/main into your main
git checkout main
git merge upstream/main
4. Push to your fork
git push origin main

Undoing Mistakes

# Undo last commit (keep changes)
git reset --soft HEAD~1
Undo last commit (discard changes)
git reset --hard HEAD~1
Undo last commit pushed to remote
git revert HEAD
git push origin main
Undo specific file changes
git checkout HEAD -- path/to/file
Fix last commit message
git commit --amend -m "New message"
Add forgotten file to last commit
git add forgotten-file
git commit --amend --no-edit

Git Hooks

Pre-Commit Hook

#!/bin/bash
.git/hooks/pre-commit
Run linting
npm run lint || exit 1
Run tests
npm test || exit 1
Check for secrets
if git diff --cached | grep -E '(password|api_key|secret)'; then
    echo "Possible secret detected. Commit aborted."
    exit 1
fi

Pre-Push Hook

#!/bin/bash
.git/hooks/pre-push
Run full test suite
npm run test:all || exit 1
Check for console.log statements
if git diff origin/main | grep -E 'console\.log'; then
    echo "Remove console.log statements before pushing."
    exit 1
fi

Anti-Patterns

# BAD: Committing directly to main
git checkout main
git commit -m "fix bug"
GOOD: Use feature branches and PRs
BAD: Committing secrets
git add .env  # Contains API keys
GOOD: Add to .gitignore, use environment variables
BAD: Giant PRs (1000+ lines)
GOOD: Break into smaller, focused PRs
BAD: "Update" commit messages
git commit -m "update"
git commit -m "fix"
GOOD: Descriptive messages
git commit -m "fix(auth): resolve redirect loop after login"
BAD: Rewriting public history
git push --force origin main
GOOD: Use revert for public branches
git revert HEAD
BAD: Long-lived feature branches (weeks/months)
GOOD: Keep branches short (days), rebase frequently
BAD: Committing generated files
git add dist/
git add node_modules/
GOOD: Add 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 |