Skip to content

.pre-commit-setup.md

Latest commit

 

History

History
125 lines (84 loc) · 2.29 KB

.pre-commit-setup.md

File metadata and controls

125 lines (84 loc) · 2.29 KB

Pre-commit Setup Guide

This project uses pre-commit hooks to maintain code quality.

Initial Setup

# 1. Initialize git (if not already done)
git init

# 2. Sync dependencies
uv sync

# 3. Install pre-commit hooks
uv run pre-commit install

# 4. (Optional) Run on all files to test
uv run pre-commit run --all-files

What Gets Checked

Ruff (Python)

  • Formatting: Code style, line length, quotes
  • Linting: Errors, warnings, code smells
  • Import sorting: Organizes imports
  • Auto-fixes: Many issues fixed automatically

Security

  • Bandit: Checks for common security issues

Type Checking

  • mypy: Static type checking

File Checks

  • Trailing whitespace removal
  • End-of-file fixes
  • YAML/TOML/JSON syntax validation
  • No large files committed
  • No merge conflicts

Documentation

  • markdownlint: Markdown formatting
  • yamllint: YAML linting

Usage

Automatic (Recommended)

Hooks run automatically on git commit:

git add .
git commit -m "Your message"
# Hooks run here - will block commit if checks fail

Manual

Run hooks manually:

# Run all hooks on all files
uv run pre-commit run --all-files

# Run specific hook
uv run pre-commit run ruff --all-files
uv run pre-commit run ruff-format --all-files

# Run on staged files only
uv run pre-commit run

Updating Hooks

# Update to latest versions
uv run pre-commit autoupdate

# Clean and reinstall
uv run pre-commit clean
uv run pre-commit install --install-hooks

Skipping Hooks (Use Sparingly!)

# Skip all hooks (not recommended)
git commit --no-verify -m "Message"

# Skip specific hook
SKIP=bandit git commit -m "Message"

Troubleshooting

"Hook failed" messages

  • Read the error output carefully
  • Most issues are auto-fixable: uv run pre-commit run --all-files
  • Fix remaining issues manually

Slow first run

  • First run downloads hook environments (one-time)
  • Subsequent runs are much faster

Hook version conflicts

uv run pre-commit clean
uv run pre-commit install --install-hooks

Configuration Files

  • .pre-commit-config.yaml: Main pre-commit configuration
  • pyproject.toml: Ruff, bandit, pytest, mypy settings
  • .yamllint.yaml: YAML linting rules
  • .markdownlint.yaml: Markdown linting rules