@heyai-rules/pilo-masterkit 2.1.0 → 3.1.0

package/.agent/skills/git-workflow/SKILL.md

@@ -1,715 +1,715 @@
----
-name: git-workflow
-description: Git workflow patterns including branching strategies, commit conventions, merge vs rebase, conflict resolution, and collaborative development best practices for teams of all sizes.
-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)
-
-```bash
-# 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)
-
-```bash
-# 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
-
-```bash
-# 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
-
-```markdown
-## 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)?
-
-**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
-# 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
-
-```bash
-# 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
-
-```bash
-# 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
-
-```bash
-# 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
-
-```bash
-# 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
-
-```bash
-# 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
-
-```bash
-# 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
-
-```bash
-# 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
-```
-
-### Useful Aliases
-
-```bash
-# 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
-
-```gitignore
-# 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
-
-```bash
-# 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
-
-```bash
-# 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
-
-```bash
-# 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
-
-```bash
-# 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
-
-```bash
-#!/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
-
-```bash
-#!/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` |
+---
+name: git-workflow
+description: Git workflow patterns including branching strategies, commit conventions, merge vs rebase, conflict resolution, and collaborative development best practices for teams of all sizes.
+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)
+
+```bash
+# 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)
+
+```bash
+# 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
+
+```bash
+# 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
+
+```markdown
+## 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)?
+
+**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
+# 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
+
+```bash
+# 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
+
+```bash
+# 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
+
+```bash
+# 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
+
+```bash
+# 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
+
+```bash
+# 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
+
+```bash
+# 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
+
+```bash
+# 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
+```
+
+### Useful Aliases
+
+```bash
+# 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
+
+```gitignore
+# 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
+
+```bash
+# 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
+
+```bash
+# 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
+
+```bash
+# 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
+
+```bash
+# 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
+
+```bash
+#!/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
+
+```bash
+#!/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` |