# Git Hooks

This directory contains git hooks that enforce code quality and testing requirements.

## Available Hooks

### pre-commit

**Purpose**: Enforces 100% unit test passing before commits.

**What it does**:
- ✅ Runs all unit tests (`uv run pytest tests/unit/ -q`)
- ✅ Blocks commit if any test fails
- ✅ Shows clear error messages
- ✅ Fast execution (~1 second)

**Installation**:

```bash
# From repository root or backend directory
cd backend
./.git-hooks/install-hooks.sh

# Or manually:
cp .git-hooks/pre-commit ../.git/hooks/pre-commit
chmod +x ../.git/hooks/pre-commit
```

**Usage**:

```bash
# Normal commit - tests run automatically
git commit -m "Add feature X"

# Bypass hook for WIP commits (feature branches only!)
git commit -m "[WIP] Work in progress" --no-verify

# ⚠️ NEVER bypass on main branch
```

**Troubleshooting**:

If the hook fails:

1. Run tests manually to see detailed errors:
   ```bash
   uv run pytest tests/unit/ -v
   ```

2. Fix the failing tests

3. Try committing again

**Uninstall**:

```bash
rm ../.git/hooks/pre-commit
```

## Why Git Hooks?

**Benefits**:
- 🛡️ Prevents broken code from being committed
- ⚡ Fast feedback (know immediately if you broke something)
- 📜 Clean history (main branch always deployable)
- 🎯 High confidence (609 tests verify behavior)

**Philosophy**:
- Unit tests are fast (<1 second) and should always pass
- If a test fails, it means you broke something
- Fix it before committing, not after

## Adding New Hooks

To add a new hook:

1. Create the hook script in `.git-hooks/`
2. Make it executable: `chmod +x .git-hooks/hook-name`
3. Update `install-hooks.sh` to install it
4. Document it in this README

## See Also

- `backend/CLAUDE.md` → "Testing Policy" section
- `backend/tests/CLAUDE.md` → "Testing Policy" section