Run Pre-commit Hooks Skill

Validate code quality with pre-commit hooks before committing.

When to Use

Before committing code
Testing if CI will pass
After making code changes
Troubleshooting commit failures

Quick Reference

# Install hooks (one-time)
pixi run pre-commit install

# Run on all files
just pre-commit-all

# Run on staged files
just precommit

# NEVER use --no-verify to bypass hooks
# Fix the code instead to pass hooks

# If a specific hook is broken (not your code):
SKIP=hook-name git commit -m "message"  # Document why in message

Configured Hooks

| Hook | Purpose | Auto-Fix | |------|---------|----------| | mojo-format | Format Mojo code | Yes | | trailing-whitespace | Remove trailing spaces | Yes | | end-of-file-fixer | Add final newline | Yes | | check-yaml | Validate YAML syntax | No | | check-added-large-files | Prevent large files | No | | mixed-line-ending | Fix line endings | Yes |

Workflow

# 1. Make changes
# ... edit files ...

# 2. Run hooks on staged files
just precommit

# 3. If hooks auto-fixed files
git add .              # Stage fixed files
git commit -m "feat: feature name"

# 4. If hooks reported errors
# Fix issues manually, then re-commit

Hook Behavior

Auto-Fix Hooks

These hooks fix issues automatically:

git commit -m "message"
# Hooks run, fix files, abort commit
# Files are fixed but not staged

git add .              # Stage fixes
git commit -m "message"  # Commit again

Check-Only Hooks

These hooks report but don't fix:

git commit -m "message"
# check-yaml fails - fix manually

# Fix YAML syntax
git add .
git commit -m "message"

Common Issues

| Error | Cause | Fix | |-------|-------|-----| | "Trailing whitespace" | Spaces at line end | Run hooks again (auto-fixed) | | "Check YAML failed" | Invalid YAML syntax | Fix YAML manually | | "Large file rejected" | File > 1MB | Use Git LFS or remove file | | "Mixed line ending" | Inconsistent line endings | Run hooks again (auto-fixed) |

Setup

# Install pre-commit (first time)
pip install pre-commit

# Install hooks (first time)
pre-commit install

# Hooks now run automatically on commit

CI Integration

Pre-commit runs in GitHub Actions:

jobs:
  precommit
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
      - run: pip install pre-commit
      - run: just pre-commit-all

Advanced Usage

# Run specific hook only
pixi run pre-commit trailing-whitespace --all-files

# Run on specific file
pixi run pre-commit --files src/tensor.mojo

# Update hook versions
pixi run pre-commit autoupdate

# Skip a specific broken hook (document reason in commit message)
SKIP=hook-name git commit -m "fix: reason for skipping hook-name"

# NEVER use --no-verify to skip all hooks

Error Handling

| Issue | Solution | |-------|----------| | Hooks not installed | Run pre-commit install | | Hooks not running | Verify .pre-commit-config.yaml exists | | All files modified after hook | Stage fixes and re-commit | | Need to skip hook | Use SKIP=hook-id git commit |

Hook Bypass Policy

STRICT POLICY: --no-verify is PROHIBITED.

Why this matters:

Pre-commit hooks catch errors before they reach CI
Bypassing hooks allows broken code into the repository
CI will reject commits that bypass hooks anyway

What to do when hooks fail:

✅ Read the error - Hook output explains what's wrong
✅ Fix your code - Update to pass the check
✅ Re-run hooks - Verify with pre-commit run
✅ Commit again - Let hooks validate

Exception for broken hooks:

If the hook itself is broken (not your code), use SKIP=hook-id:

# Example: trailing-whitespace hook is broken
SKIP=trailing-whitespace git commit -m "fix: skip broken hook (see issue #123)"

Never acceptable:

❌ git commit --no-verify
❌ git commit -n
❌ Bypassing all hooks

References

Git Commit Policy - Strict enforcement rules
Configuration: .pre-commit-config.yaml
Related skill: quality-fix-formatting for manual fixes
Related skill: quality-run-linters for all linters