---
name: Git Workflow
description: Use this skill for version control, branching strategy, commit conventions, and pull request management. Essential for safe feature development.
version: 1.0.0
---

# Git Workflow Skill

> Safe version control for solo developers and small teams.

---

## Why This Matters

Git protects you from:
- ❌ Losing work
- ❌ Breaking production with untested code
- ❌ Not being able to undo mistakes
- ❌ Confusion about what changed and when

**Good git habits = safe development.**

---

## The Simple Branching Strategy

For solo developers/small teams, use this flow:

```
main (production-ready)
  │
  ├── develop (integration branch)
  │     │
  │     ├── feature/user-auth
  │     ├── feature/dashboard
  │     └── fix/login-bug
  │
  └── (hotfix/urgent-fix - only for emergencies)
```

### Branch Types

| Branch | Purpose | Merges Into |
|--------|---------|-------------|
| `main` | Production code, always deployable | - |
| `develop` | Integration, latest features | main |
| `feature/*` | New features | develop |
| `fix/*` | Bug fixes | develop |
| `hotfix/*` | Emergency production fixes | main + develop |

---

## Daily Workflow

### Starting a New Feature

```bash
# 1. Start from develop (not main!)
git checkout develop
git pull origin develop

# 2. Create feature branch
git checkout -b feature/add-user-profile

# 3. Work on your feature...
# Make commits as you go (see commit conventions below)

# 4. When done, push to remote
git push -u origin feature/add-user-profile

# 5. Create Pull Request (develop ← feature/add-user-profile)
```

### Making Commits

```bash
# 1. UPDATE CHANGELOG FIRST!
# Edit docs/CHANGELOG.md and add your changes under [Unreleased]

# 2. Stage specific files
git add src/components/UserProfile.tsx
git add docs/CHANGELOG.md

# Or stage all changes
git add .

# 3. Commit with meaningful message
git commit -m "feat: add user profile component with avatar upload"

# 4. Push to remote
git push
```

### ⚠️ IMPORTANT: Update CHANGELOG

**Before EVERY commit:**
1. Open `docs/CHANGELOG.md`
2. Add entry under `[Unreleased]` section
3. Use appropriate category:
   - `Added` for new features
   - `Fixed` for bug fixes
   - `Changed` for modifications
   - `Security` for security updates

**Example:**
```markdown
## [Unreleased]

### Added
- User profile component with avatar upload
- Profile editing functionality
- 5 tests for profile features

### Fixed
- Avatar upload size validation
```

### Merging to Develop

```bash
# Option 1: Via GitHub PR (recommended)
# Create PR on GitHub, review, then merge

# Option 2: Local merge
git checkout develop
git pull origin develop
git merge feature/add-user-profile
git push origin develop

# Delete feature branch after merge
git branch -d feature/add-user-profile
git push origin --delete feature/add-user-profile
```

### Deploying to Production

```bash
# When develop is tested and ready
git checkout main
git pull origin main
git merge develop
git push origin main

# Tag the release
git tag -a v1.0.0 -m "Release version 1.0.0"
git push origin v1.0.0
```

---

## Commit Message Conventions

Use **Conventional Commits** format:

```
<type>: <short description>

[optional body]
[optional footer]
```

### Types

| Type | When to Use | Example |
|------|-------------|---------|
| `feat` | New feature | `feat: add user authentication` |
| `fix` | Bug fix | `fix: resolve login redirect loop` |
| `docs` | Documentation | `docs: update README with setup steps` |
| `style` | Formatting (no logic change) | `style: fix indentation in UserCard` |
| `refactor` | Code restructure (no feature change) | `refactor: extract validation to utils` |
| `test` | Adding tests | `test: add unit tests for auth service` |
| `chore` | Maintenance | `chore: update dependencies` |

### Good Commit Examples

```bash
# Feature
git commit -m "feat: add OAuth login with Google"

# Bug fix
git commit -m "fix: prevent duplicate form submissions"

# With scope
git commit -m "feat(auth): add password reset flow"

# Breaking change
git commit -m "feat!: change API response format

BREAKING CHANGE: API now returns { data, error } instead of raw data"
```

### Bad Commit Examples

```bash
# ❌ Too vague
git commit -m "update"
git commit -m "fix stuff"
git commit -m "wip"

# ❌ Too long
git commit -m "added the user profile page with avatar upload and also fixed some bugs and updated the styles"
```

---

## Pull Request Process

### Creating a Good PR

```markdown
## Summary
Brief description of what this PR does.

## Changes
- Added UserProfile component
- Created avatar upload functionality
- Added profile API endpoint

## Testing
- [ ] Tested locally
- [ ] Added unit tests
- [ ] Tested on mobile

## Screenshots
(if UI changes)
```

### PR Checklist

Before requesting review:

- [ ] Code compiles without errors
- [ ] All tests pass
- [ ] No console.log statements left
- [ ] Follows project conventions
- [ ] Branch is up-to-date with develop

### Merging PRs

**Squash and Merge** (recommended for clean history):
- Combines all commits into one
- Keeps main/develop history clean

**Merge Commit**:
- Preserves all individual commits
- Use for larger features where history matters

---

## Handling Common Situations

### Oops, Wrong Branch!

```bash
# Stash changes
git stash

# Switch to correct branch
git checkout feature/correct-branch

# Apply stashed changes
git stash pop
```

### Need to Undo Last Commit

```bash
# Undo commit but keep changes
git reset --soft HEAD~1

# Undo commit and discard changes (careful!)
git reset --hard HEAD~1
```

### Merge Conflicts

```bash
# When you see conflicts during merge
git status  # See conflicted files

# Open each file, look for conflict markers:
<<<<<<< HEAD
your code
=======
their code
>>>>>>> feature/other

# Edit to resolve, then:
git add <resolved-file>
git commit -m "fix: resolve merge conflicts"
```

### Sync Feature Branch with Develop

```bash
# On your feature branch
git checkout feature/my-feature

# Get latest from develop
git fetch origin
git merge origin/develop

# Or rebase (cleaner but more advanced)
git rebase origin/develop
```

---

## Quick Reference Commands

### Status & Info
```bash
git status              # Current state
git log --oneline -10   # Recent commits
git branch -a           # All branches
git diff                # Unstaged changes
git diff --staged       # Staged changes
```

### Branching
```bash
git checkout -b name    # Create and switch
git checkout name       # Switch to existing
git branch -d name      # Delete local branch
git push origin --delete name  # Delete remote
```

### Saving Work
```bash
git add .               # Stage all
git add <file>          # Stage specific
git commit -m "msg"     # Commit
git push                # Push to remote
git stash               # Temporarily save
git stash pop           # Restore saved
```

### Syncing
```bash
git fetch               # Get remote changes (no merge)
git pull                # Fetch + merge
git push                # Send to remote
```

---

## Git for Solo Developers

If you're working alone, you can simplify:

### Minimal Flow
```bash
# Work directly on develop for small projects
git checkout develop

# Make changes
git add .
git commit -m "feat: add feature"
git push

# When ready for production
git checkout main
git merge develop
git push
```

### When to Use Feature Branches (Even Solo)

Use feature branches when:
- The feature takes more than a day
- It might break existing functionality
- You want to be able to abandon it
- You're experimenting

---

## GitHub CLI Shortcuts

```bash
# Create PR from command line
gh pr create --title "Add user profile" --body "Description here"

# List PRs
gh pr list

# View PR
gh pr view 123

# Merge PR
gh pr merge 123 --squash
```

---

## Visual: Complete Feature Workflow

```
1. git checkout develop
2. git pull origin develop
3. git checkout -b feature/new-thing
         │
         ├─── git add .
         ├─── git commit -m "feat: start new thing"
         ├─── ... more commits ...
         ├─── git push -u origin feature/new-thing
         │
4. Create PR on GitHub (develop ← feature/new-thing)
5. Review, test, approve
6. Merge PR (squash)
7. Delete feature branch
8. git checkout develop && git pull
```

---

*This skill ensures your code changes are tracked, reversible, and safely integrated.*