# Git Workflow

> Git workflow best practices for the career_ios_backend project. Automatically invoked when user mentions git operations, commits, pushes, or version control. Trigger keywords: "git", "commit", "push", "pull", "branch", "merge", "提交", "推送" Enforces pre-commit hooks, security checks, and documentation requirements.

- Skill: `majiayu000/git-workflow-34` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add majiayu000/git-workflow-34`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/git-workflow-34/raw
- Safety review: pending (external: skill-scanner PASS, skillspector FAIL)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/majiayu000/git-workflow-34

---


# Git Workflow Skill

## Purpose
Enforce git best practices, pre-commit hooks, and mandatory documentation updates for the career_ios_backend project.

## Automatic Activation

This skill is AUTOMATICALLY activated when user mentions:
- ✅ "git commit"
- ✅ "git push"
- ✅ "ready to commit/push"
- ✅ "提交代碼"
- ✅ "推送到遠端"

---

## Git Hooks Setup

### First-Time Installation

```bash
# Install pre-commit and pre-push hooks
poetry run pre-commit install
poetry run pre-commit install --hook-type pre-push
```

### Pre-Commit Checks (Fast ~5 seconds)

When you run `git commit`, these checks run automatically:

1. ✅ **Branch Check** - Prevents commits to main/master
2. ✅ **Ruff Linting & Formatting** - Auto-fixes code style
3. ✅ **File Checks** - Trailing whitespace, YAML/TOML syntax
4. ✅ **Security Checks** - Prevents leaking:
   - API keys
   - Secrets
   - Private keys
   - Credentials

### Pre-Push Checks (Smoke Tests ~10 seconds)

When you run `git push`, these tests run automatically:

1. ✅ **Critical Console API Smoke Tests**
   - Login functionality
   - Client management core features
   - Case/Session core features
   - Full test suite (106+ tests) runs in CI

---

## Commit Workflow

### Step-by-Step Process

```bash
# 1. Check current branch
git branch --show-current
# ⚠️ MUST NOT be on main/master

# 2. Stage changes
git add .

# 3. Commit (triggers pre-commit hooks ~5s)
git commit -m "feat: add XXX API"
# ↓ Auto-executes:
#   ✅ Branch check
#   ✅ Ruff linting/formatting
#   ✅ Security checks
#   ✅ File checks

# 4. Push (triggers smoke tests ~10s)
git push
# ↓ Auto-executes:
#   ✅ Critical Console API smoke tests
#   ✅ Full tests run in CI (106+ tests)
```

### Commit Message Format

Follow conventional commits:

✅ **Good Examples**:
- `feat: add user login API`
- `fix: correct client code generation`
- `docs: update API guide`
- `test: add session API tests`
- `refactor: extract session service`

❌ **Bad Examples**:
- `update code` (too vague)
- `fixes` (no description)
- `feat: add user login API 🤖 Generated with Claude Code` (no Claude signature!)

---

## Manual Hook Execution (Optional)

```bash
# Run all pre-commit checks manually
poetry run pre-commit run --all-files

# Run pre-push smoke tests manually
poetry run pre-commit run --hook-stage push

# Run full integration test suite manually (106+ tests)
poetry run pytest tests/integration/ -v
```

---

## 🚨 ABSOLUTELY FORBIDDEN

### NEVER Use --no-verify

```bash
# ❌ NEVER DO THIS:
git commit --no-verify
git push --no-verify

# These bypass security checks and will:
# - Allow commits to main/master
# - Skip security scans (leak secrets)
# - Skip tests (break production)
# - Violate project standards
```

**Why it's forbidden**:
- Bypasses security checks → Risk of leaking credentials
- Skips tests → Risk of breaking production
- Violates TDD → Degrades code quality
- Breaks CI/CD pipeline → Deployment failures

### If Hooks Fail

**DO NOT** skip checks with `--no-verify`!

**INSTEAD**:
1. Read the error message
2. Fix the actual problem
3. Re-run the commit/push

Common failures and solutions:

```bash
# Failure: "Detected secrets in code"
Solution: Remove the secret, use environment variables

# Failure: "Ruff check failed"
Solution: Run `ruff check --fix app/` to auto-fix

# Failure: "Tests failed"
Solution: Fix the broken tests, don't skip them

# Failure: "On main branch"
Solution: Create/switch to feature branch
```

---

## 📚 MANDATORY Documentation Updates

**CRITICAL**: Before EVERY `git push`, you MUST update documentation.

### Required Updates

```bash
# 1. Update PRD.md
- Version number (if releasing)
- New features added
- Current status

# 2. Update CHANGELOG.md
- Add changes to [Unreleased] section
- Follow Keep a Changelog format

# 3. Update CHANGELOG_zh-TW.md
- Sync with English CHANGELOG.md
- Maintain same structure

# 4. Weekly Report (if new week)
- Update progress report
- Document blockers/achievements
```

### Enforcement

```bash
# Agent will CHECK before allowing push:
git push
  ↓
Agent checks:
  ❌ PRD.md not updated → BLOCK PUSH
  ❌ CHANGELOG.md [Unreleased] empty → BLOCK PUSH
  ❌ CHANGELOG_zh-TW.md out of sync → BLOCK PUSH
  ✅ All docs updated → ALLOW PUSH
```

**NO EXCEPTIONS**: Even small changes require documentation updates.

---

## Branch Strategy

### Current Branch Structure

```
main/master (protected)
  ↓
staging (main development)
  ↓
feature/xxx (your work)
  ↓
parents_rag_refine (current)
```

### Branch Rules

1. **NEVER commit directly to main/master**
   - Pre-commit hook will BLOCK
   - Always use staging or feature branches

2. **Create feature branches from staging**
   ```bash
   git checkout staging
   git pull
   git checkout -b feature/new-feature-name
   ```

3. **Merge back to staging when complete**
   ```bash
   # After tests pass and code reviewed
   git checkout staging
   git merge feature/new-feature-name
   git push
   ```

---

## Common Git Operations

### Starting New Work

```bash
# 1. Update staging
git checkout staging
git pull

# 2. Create feature branch
git checkout -b feature/add-client-search

# 3. Work on feature
# ... make changes ...

# 4. Commit regularly
git add .
git commit -m "feat: add client search endpoint"

# 5. Push to remote
git push -u origin feature/add-client-search
```

### Reviewing Before Push

```bash
# Check what will be committed
git status

# Review changes
git diff

# Review staged changes
git diff --staged

# Check recent commits
git log --oneline -5
```

### Fixing Mistakes

```bash
# Undo last commit (keep changes)
git reset --soft HEAD~1

# Undo last commit (discard changes) ⚠️ DESTRUCTIVE
git reset --hard HEAD~1

# Amend last commit message
git commit --amend -m "new message"

# Unstage file
git restore --staged <file>
```

---

## Integration with TDD Workflow

Git workflow integrates with TDD:

```
TDD Cycle:
  1. RED: Write failing test
  2. GREEN: Implement minimal code
  3. REFACTOR: Improve quality
     ↓
  4. GIT COMMIT ← You are here
     - Pre-commit hooks run
     - Security checks pass
     - Code formatted
     ↓
  5. GIT PUSH
     - Smoke tests run
     - Documentation verified
     - CI/CD triggered
```

---

## Quality Gates Checklist

### Before Commit

- [ ] All integration tests pass locally
- [ ] Code follows project patterns
- [ ] No hardcoded credentials
- [ ] Commit message follows format
- [ ] On correct branch (not main/master)

### Before Push

- [ ] Documentation updated (PRD, CHANGELOG)
- [ ] All commits have good messages
- [ ] No sensitive data in commits
- [ ] Ready for code review
- [ ] CI/CD pipeline will pass

---

## Troubleshooting

### "Hook script not found"

```bash
# Reinstall hooks
poetry run pre-commit install
poetry run pre-commit install --hook-type pre-push
```

### "Permission denied" on hooks

```bash
# Fix permissions
chmod +x .git/hooks/pre-commit
chmod +x .git/hooks/pre-push
```

### "Pre-commit hook takes too long"

This is normal:
- Pre-commit: ~5 seconds (formatting, security)
- Pre-push: ~10 seconds (smoke tests)
- Full CI: ~2 minutes (all 106+ tests)

### "I need to force push"

⚠️ **Be careful with force push**:

```bash
# Safe force push (recommended)
git push --force-with-lease

# Unsafe force push (avoid)
git push --force  # ⚠️ Can lose others' work
```

**Never force push to main/master** - will be rejected by remote.

---

## Success Metrics

- ✅ Zero commits to main/master branch
- ✅ 100% commits pass pre-commit hooks
- ✅ All pushes have updated documentation
- ✅ No use of `--no-verify` flag
- ✅ All commits follow message format

---

## Related Skills

- **tdd-workflow** - For test-first development
- **quality-standards** - For code quality requirements
- **api-development** - For API development patterns

---

**Skill Version**: v1.0
**Last Updated**: 2025-12-25
**Project**: career_ios_backend (Prototype Phase)