# Git Hooks Setup
This project uses git hooks to ensure code quality and consistency. These hooks automatically run checks before commits to catch issues early.
## Quick Start
Run the setup script to configure your git hooks:
```bash
./scripts/setup-hooks.sh
```
This will present you with options for different hook configurations.
## Available Hook Configurations
### 1. Full Checks (Recommended for releases)
- ✅ Code formatting (`cargo fmt`)
- ✅ Clippy linting (`cargo clippy`)
- ✅ Build verification (`cargo check`)
- ✅ Test execution (`cargo test`)
**Use when:** Making important commits, before creating PRs
### 2. Light Checks (Recommended for development)
- ✅ Code formatting (`cargo fmt`)
- ✅ Clippy linting (`cargo clippy`)
**Use when:** Regular development, frequent commits
### 3. Format Only (Fastest)
- ✅ Code formatting (`cargo fmt`)
**Use when:** Quick fixes, documentation changes
### 4. No Hooks
- Disables all pre-commit checks
**Use when:** You want to handle checks manually
## Manual Commands
If you prefer to run checks manually:
```bash
# Check formatting
cargo fmt --all -- --check
# Fix formatting
cargo fmt --all
# Run clippy
cargo clippy --all-targets --all-features -- -D warnings
# Run tests
cargo test --all-features
# Run all CI checks locally
./scripts/check-all.sh
```
## Bypassing Hooks
If you need to commit without running hooks (use sparingly):
```bash
git commit --no-verify -m "Your commit message"
```
## Understanding the CI Failure
The CI failure you saw was from the **Format Check** job in `.github/workflows/ci.yml`. This job runs:
```bash
cargo fmt --all -- --check
```
This command checks if all Rust code follows the standard formatting rules. The failure showed formatting differences like:
- Missing or extra blank lines
- Incorrect indentation
- Inconsistent spacing
## How the Hooks Help
The pre-commit hooks automatically:
1. **Format your code** - Runs `cargo fmt --all` and re-stages the formatted files
2. **Check for linting issues** - Runs `cargo clippy` to catch common mistakes
3. **Verify compilation** - Ensures your code builds
4. **Run tests** - Validates that your changes don't break existing functionality
## Troubleshooting
### Hook not running
- Ensure the hook file is executable: `chmod +x .git/hooks/pre-commit`
- Check that you're in the git repository root
### Hook failing
- Read the error message carefully
- Fix the reported issues
- Try committing again
- Use `git commit --no-verify` as a last resort
### Clippy warnings
- Fix the warnings by following clippy's suggestions
- Some warnings can be allowed with `#[allow(clippy::warning_name)]`
- Discuss with the team if you think a clippy rule should be disabled project-wide
### Tests failing
- Fix the failing tests
- If tests are flaky, investigate and fix the root cause
- Use `git commit --no-verify` only if you're certain the failures are unrelated
## Configuration
### Customizing Clippy Rules
Add clippy configuration to `Cargo.toml`:
```toml
[workspace.lints.clippy]
# Allow specific clippy lints
too_many_arguments = "allow"
# Deny specific lints
unwrap_used = "deny"
```
### Customizing Rustfmt
Create a `rustfmt.toml` file in the project root:
```toml
# Example rustfmt configuration
max_width = 100
hard_tabs = false
tab_spaces = 4
```
## Best Practices
1. **Run checks locally** before pushing with `./scripts/check-all.sh`
2. **Fix issues promptly** rather than bypassing hooks
3. **Use appropriate hook level** for your workflow
4. **Keep commits atomic** - each commit should be a logical unit
5. **Write descriptive commit messages** explaining the changes
## Integration with IDEs
Most Rust-compatible IDEs can be configured to:
- Format code on save
- Show clippy warnings in real-time
- Run tests automatically
This reduces the likelihood of hook failures.