Git Workflow

# Git Workflow

Systematic Git and GitHub workflows following Conventional Commits and your project's commit standards.

## Overview

This skill enforces:
- Atomic commits with clear intent (GH-3)
- Conventional Commits format (GH-1)
- Safe branch management and PR workflows
- Conflict resolution without data loss
- Issue linking and auto-close patterns

Apply when committing, branching, merging, or opening PRs.

## Commit Message Structure

Use this exact format:

```
<type>[optional scope]: <description>

[optional body]

[optional footer(s)]
```

### Commit Types

- `feat`: New feature (MINOR version bump)
- `fix`: Bug patch (PATCH version bump)
- `docs`: Documentation only
- `style`: Formatting, whitespace (no logic change)
- `refactor`: Code restructure (no bug fix or feature)
- `perf`: Performance improvement
- `test`: Add or fix tests
- `build`: Build system or dependencies
- `ci`: CI/CD configuration
- `chore`: Maintenance (gitignore, etc.)
- `revert`: Revert previous commit

### Breaking Changes

Mark with `!` or footer:

```
feat!: drop Node 12 support

BREAKING CHANGE: requires Node 14+
```

### Rules

**GH-1 (MUST)**: Use Conventional Commits format
**GH-2 (SHOULD NOT)**: Never mention Claude or Anthropic
**GH-3 (MUST)**: Commits must be atomic and communicate intent
**GH-4 (MUST)**: Verbose beats ambiguous

### Good Examples

```
feat(auth): add password reset via email
fix(api): prevent race condition in user creation
docs: update README environment variables
refactor(db): extract user queries to separate module
test(payments): add Stripe webhook integration tests
```

### Anti-Patterns

```
update stuff           # ❌ What stuff?
fix bug                # ❌ Which bug?
wip                    # ❌ Work in progress is not a commit
asdfasdf               # ❌ Keyboard mashing
final version          # ❌ Meaningless
Claude helped me       # ❌ Violates GH-2
```

## Branching Strategy

### Branch Types and Naming

```
main                    # Production-ready, always stable
develop                 # Integration (if using Gitflow)
feature/user-auth       # New features
fix/payment-validation  # Bug fixes
hotfix/security-cors    # Critical production fixes
release/v2.1.0          # Release preparation
```

### Feature Branch Workflow

```bash
# 1. Create branch from main
git checkout main
git pull origin main
git checkout -b feature/my-feature

# 2. Work and commit atomically
git add file1.ts file2.ts
git commit -m "feat(feature): implement core logic"

# 3. Push and open PR
git push origin feature/my-feature

# 4. After merge, cleanup
git checkout main
git pull origin main
git branch -d feature/my-feature
```

## Pull Request Workflow

### Opening a PR

**Title**: Use Conventional Commit format

```
feat(payments): integrate Stripe payment processing
```

**Description template**:

```markdown
## Description
[What changed and why]

## Related Issues
Closes #123

## Changes Made
- Added X
- Fixed Y  
- Refactored Z

## Testing
- [ ] Unit tests pass
- [ ] Integration tests pass
- [ ] Manual testing complete

## Breaking Changes
[If any]
```

### Pre-Merge Checklist

Before merging, verify:

- [ ] CI checks pass (prettier, eslint, TypeScript, tests)
- [ ] At least one approval (team policy)
- [ ] All conversations resolved
- [ ] Branch up-to-date with base
- [ ] Commit messages follow conventions

### Merge Strategy

**Squash and merge** (recommended): Clean history, single commit per feature
**Rebase and merge**: Linear history, preserve commit details
**Merge commit**: Full branch history preserved

## Merge Conflict Resolution

### Detection

Conflicts occur during:
- `git merge`
- `git pull`
- `git rebase`

Check status:
```bash
git status  # Shows conflicted files
```

### Manual Resolution Process

**Step 1**: Open conflicted file

Git marks conflicts with:
```
const value = 20;
```

**Step 2**: Resolve conflict

Edit file, remove markers, keep desired code:
```ts
const value = 20;
```

**Step 3**: Stage resolved file

```bash
git add path/to/file
```

**Step 4**: Complete merge

```bash
git commit -m "fix: resolve merge conflict in [file]"
```

### Strategy Options

Accept one side entirely:

```bash
# Keep current branch changes
git merge -s recursive -Xours feature-branch

# Keep incoming branch changes
git merge -s recursive -Xtheirs feature-branch
```

### Abort Merge

If stuck:
```bash
git merge --abort  # Resets to pre-merge state
```

### GitHub Web Resolution

For simple conflicts:
1. Open PR → "Resolve conflicts"
2. Edit in web editor
3. Remove `<<<<<<<`, `=======`, `>>>>>>>`
4. "Mark as resolved" → "Commit merge"

Note: Complex conflicts need command line.

## Issue Management

### Linking Issues to PRs

Use auto-close keywords in commit messages or PR description:

```
Closes #123
Fixes #456
Resolves #789
```

Multiple issues:
```
Closes #123, #456, #789
```

### Standard Labels

- `bug`: Something broken
- `feature`: New functionality
- `enhancement`: Improvement to existing
- `documentation`: Docs updates
- `good first issue`: Beginner-friendly
- `help wanted`: Need assistance
- `wontfix`: Won't be addressed
- `duplicate`: Already reported

## Pre-Commit Checklist

Before every commit, verify:

- [ ] Code follows CLAUDE.md guidelines
- [ ] Tests written and passing
- [ ] TypeScript compiles (`npx tsc --noEmit`)
- [ ] Linting passes (`pnpm lint`)
- [ ] Formatting applied (`npx prettier --write .`)
- [ ] No sensitive data (API keys, passwords)
- [ ] Commit message uses Conventional Commits
- [ ] Changes are atomic and focused

## Common Workflows

### Scenario 1: Feature Development

```bash
git checkout main
git pull origin main
git checkout -b feature/new-dashboard

# Work and commit
git add .
git commit -m "feat(dashboard): add user analytics view"

# Push and open PR
git push origin feature/new-dashboard
# Open PR on GitHub

# After merge
git checkout main
git pull origin main
git branch -d feature/new-dashboard
```

### Scenario 2: Hotfix

```bash
git checkout mai