# Git Workflow

## Daily Workflow

### Start Fresh
```bash
git checkout main
git pull origin main
git checkout -b feature/descriptive-name
```

### Commit Frequently

Create a commit after ANY of these:
- Completing a single feature or function
- Fixing a bug (even small ones)
- Adding or modifying tests
- Updating documentation
- Before switching to a different task
- Every 15-30 minutes of active coding (at natural breakpoints)

**When NOT to commit:**
- Code doesn't run/compile
- Broken functionality
- Incomplete features with no clean boundary

### Push for Backup
```bash
git push -u origin feature/branch-name    # First time
git push origin feature/branch-name       # Subsequent pushes
```

## Branch Naming

```
feature/add-user-auth       # New features
bugfix/fix-login-error      # Bug fixes
hotfix/critical-security    # Urgent fixes
docs/update-readme          # Documentation
refactor/cleanup-database   # Code improvements
```

## Conventional Commits

All commits MUST follow conventional commits:

```
<type>(<optional-scope>): <description>

[optional body]
```

### Types

| Type | Description |
|------|-------------|
| `feat` | New feature |
| `fix` | Bug fix |
| `docs` | Documentation |
| `style` | Formatting (no code change) |
| `refactor` | Code restructure (no behavior change) |
| `test` | Adding or updating tests |
| `chore` | Maintenance, dependencies |
| `perf` | Performance improvement |
| `ci` | CI/CD changes |

### Scope (optional)

Indicates the area affected:
```bash
feat(auth): Add password reset flow
fix(api): Handle timeout errors
test(auth): Add integration tests for login flow
```

### Good Messages
```bash
git commit -m "feat: Add user authentication with JWT tokens"
git commit -m "fix: Resolve memory leak in image processing"
git commit -m "refactor: Extract validation into shared module"
```

### Bad Messages
```bash
git commit -m "fix"           # Too vague
git commit -m "updates"       # Meaningless
git commit -m "WIP"           # Not descriptive
git commit -m "Fixed bug"     # Missing type prefix
```

### Why Conventional Commits?

1. **Automated changelogs** — tools can categorize changes by type
2. **Clear history** — easy to understand what changed and why
3. **Semantic versioning** — `feat` = minor, `fix` = patch
4. **Searchable** — `git log --grep="feat:"` finds all features

## Proactive Git Behavior

After completing a logical unit of work:
1. Run tests and linter (if configured)
2. Stage and commit with a conventional commit message
3. Inform the user: "I've committed this change: `feat: ...`"

If uncommitted changes accumulate, proactively suggest committing.

## Team Collaboration

1. **Never commit to main directly** — always use feature branches
2. **Always pull before push** — `git pull origin main` first
3. **Use meaningful branch names** — not `test`, `mywork`, `temp`
4. **Merge via Pull Requests** — for code review and history

## Recovery Commands

### Uncommitted Changes
```bash
git status                    # See what changed
git checkout -- filename      # Restore single file
git stash                     # Temporarily save work
git stash pop                 # Restore saved work
```

### Committed But Not Pushed
```bash
git reset --soft HEAD~1       # Undo commit, keep changes staged
git reset HEAD~1              # Undo commit, unstage changes
```

### Already Pushed (Safe)
```bash
git revert HEAD               # Create undo commit
git push origin branch-name
```

### Emergency Recovery
```bash
git reflog                    # See all actions (your safety net)
git checkout abc1234          # Go back to specific state
```

## Danger Commands (Confirm Before Using)

```bash
git reset --hard HEAD         # Deletes all uncommitted work
git push --force              # Overwrites remote history
git branch -D branch-name     # Force delete branch
```