affaan-m/everything-claude-code/git-workflow

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

main (trunk)
  │
  ├── short-lived feature (1-2 days max)
  ├── short-lived feature
  └── short-lived feature

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

<type>(<scope>): <subject>
 
[optional body]
 
[optional footer(s)]

# 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"

# <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

# Creates a merge commit
git checkout main
git merge feature/user-auth
 
# Result:
# *   merge commit
# |\
# | * feature commits
# |/
# * main commits

# Rewrites feature commits onto target branch
git checkout feature/user-auth
git rebase main
 
# Result:
# * feature commits (rewritten)
# * main commits

# 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

# 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

<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

## 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

# 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.

# 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

# 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

# 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

# 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

# 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}

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)

# 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

# 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

# User identity
git config --global user.name "Your Name"
git config --global user.email "your@email.com"
 
# 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

# 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

# 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

# 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

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