majiayu000 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-formattingfor manual fixes - Related skill:
quality-run-lintersfor all linters