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

bash

# 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

bash

# 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:

bash

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:

bash

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

bash

# 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:

yaml

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

bash

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

# Run on specific file
pixi run pre-commit --files scylla/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:

bash

# 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