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

Commit Messages

Conventional Commits Format

<type>(<scope>): <subject>

[optional body]

[optional footer(s)]

Types

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)

bash
1# Creates a merge commit
2git checkout main
3git merge feature/user-auth
4
5# Result:
6# *   merge commit
7# |\
8# | * feature commits
9# |/
10# * 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)

bash
1# Rewrites feature commits onto target branch
2git checkout feature/user-auth
3git rebase main
4
5# Result:
6# * feature commits (rewritten)
7# * 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

bash
1# Update feature branch with latest main (before PR)
2git checkout feature/user-auth
3git fetch origin
4git rebase origin/main
5
6# Fix any conflicts
7# Tests should still pass
8
9# Force push (only if you're the only contributor)
10git 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

markdown
1## What
2
3Brief description of what this PR does.
4
5## Why
6
7Explain the motivation and context.
8
9## How
10
11Key implementation details worth highlighting.
12
13## Testing
14
15- [ ] Unit tests added/updated
16- [ ] Integration tests added/updated
17- [ ] Manual testing performed
18
19## Screenshots (if applicable)
20
21Before/after screenshots for UI changes.
22
23## Checklist
24
25- [ ] Code follows project style guidelines
26- [ ] Self-review completed
27- [ ] Comments added for complex logic
28- [ ] Documentation updated
29- [ ] No new warnings introduced
30- [ ] Tests pass locally
31- [ ] Related issues linked
32
33Closes #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)?

For Authors:

• 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

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

Resolve Conflicts

bash
1# See conflicted files
2git status
3
4# View conflict markers in file
5# <<<<<<< HEAD
6# content from main
7# =======
8# content from feature branch
9# >>>>>>> feature/user-auth
10
11# Option 1: Manual resolution
12# Edit file, remove markers, keep correct content
13
14# Option 2: Use merge tool
15git mergetool
16
17# Option 3: Accept one side
18git checkout --ours src/auth/login.ts    # Keep main version
19git checkout --theirs src/auth/login.ts  # Keep feature version
20
21# After resolving, stage and commit
22git add src/auth/login.ts
23git commit

Conflict Prevention Strategies

bash
1# 1. Keep feature branches small and short-lived
2# 2. Rebase frequently onto main
3git checkout feature/user-auth
4git fetch origin
5git rebase origin/main
6
7# 3. Communicate with team about touching shared files
8# 4. Use feature flags instead of long-lived branches
9# 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

bash
1# Delete local branches that are merged
2git branch --merged main | grep -v "^\*\|main" | xargs -n 1 git branch -d
3
4# Delete remote-tracking references for deleted remote branches
5git fetch -p
6
7# Delete local branch
8git branch -d feature/user-auth  # Safe delete (only if merged)
9git branch -D feature/user-auth  # Force delete
10
11# Delete remote branch
12git push origin --delete feature/user-auth

Stash Workflow

bash
1# Save work in progress
2git stash push -m "WIP: user authentication"
3
4# List stashes
5git stash list
6
7# Apply most recent stash
8git stash pop
9
10# Apply specific stash
11git stash apply stash@{2}
12
13# Drop stash
14git 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

bash
1# Create annotated tag
2git tag -a v1.2.0 -m "Release v1.2.0
3
4Features:
5- Add user authentication
6- Implement password reset
7
8Fixes:
9- Resolve login redirect issue
10
11Breaking Changes:
12- None"
13
14# Push tag to remote
15git push origin v1.2.0
16
17# List tags
18git tag -l
19
20# Delete tag
21git tag -d v1.2.0
22git push origin --delete v1.2.0

Changelog Generation

bash
1# Generate changelog from commits
2git log v1.1.0..v1.2.0 --oneline --no-merges
3
4# Or use conventional-changelog
5npx conventional-changelog -i CHANGELOG.md -s

Git Configuration

Essential Configs

bash
1# User identity
2git config --global user.name "Your Name"
3git config --global user.email "your@email.com"
4
5# Default branch name
6git config --global init.defaultBranch main
7
8# Pull behavior (rebase instead of merge)
9git config --global pull.rebase true
10
11# Push behavior (push current branch only)
12git config --global push.default current
13
14# Auto-correct typos
15git config --global help.autocorrect 1
16
17# Better diff algorithm
18git config --global diff.algorithm histogram
19
20# Color output
21git config --global color.ui auto

Useful Aliases

bash
1# Add to ~/.gitconfig
2[alias]
3    co = checkout
4    br = branch
5    ci = commit
6    st = status
7    unstage = reset HEAD --
8    last = log -1 HEAD
9    visual = log --oneline --graph --all
10    amend = commit --amend --no-edit
11    wip = commit -m "WIP"
12    undo = reset --soft HEAD~1
13    contributors = shortlog -sn

Gitignore Patterns

gitignore
1# Dependencies
2node_modules/
3vendor/
4
5# Build outputs
6dist/
7build/
8*.o
9*.exe
10
11# Environment files
12.env
13.env.local
14.env.*.local
15
16# IDE
17.idea/
18.vscode/
19*.swp
20*.swo
21
22# OS files
23.DS_Store
24Thumbs.db
25
26# Logs
27*.log
28logs/
29
30# Test coverage
31coverage/
32
33# Cache
34.cache/
35*.tsbuildinfo

Common Workflows

Starting a New Feature

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

Updating a PR with New Changes

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

Syncing Fork with Upstream

bash
1# 1. Add upstream remote (once)
2git remote add upstream https://github.com/original/repo.git
3
4# 2. Fetch upstream
5git fetch upstream
6
7# 3. Merge upstream/main into your main
8git checkout main
9git merge upstream/main
10
11# 4. Push to your fork
12git push origin main

Undoing Mistakes

bash
1# Undo last commit (keep changes)
2git reset --soft HEAD~1
3
4# Undo last commit (discard changes)
5git reset --hard HEAD~1
6
7# Undo last commit pushed to remote
8git revert HEAD
9git push origin main
10
11# Undo specific file changes
12git checkout HEAD -- path/to/file
13
14# Fix last commit message
15git commit --amend -m "New message"
16
17# Add forgotten file to last commit
18git add forgotten-file
19git commit --amend --no-edit

Git Hooks

Pre-Commit Hook

bash
1#!/bin/bash
2# .git/hooks/pre-commit
3
4# Run linting
5npm run lint || exit 1
6
7# Run tests
8npm test || exit 1
9
10# Check for secrets
11if git diff --cached | grep -E '(password|api_key|secret)'; then
12    echo "Possible secret detected. Commit aborted."
13    exit 1
14fi

Pre-Push Hook

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

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