Skip to content

Pre-commit Hooks Setup

This project uses pre-commit to automatically run code quality checks before each commit.

Installation

Pre-commit hooks are installed automatically when you run:

task env:setup

This command: 1. Syncs Python dependencies (including pre-commit) 2. Installs the git pre-commit hook

What Checks Run

The following checks run automatically on every commit:

Commit Message Validation (commitizen)

  • Validates that commit messages follow Conventional Commits format
  • Required format: type(scope): description (e.g., feat(wifi): add AP mode)

File Formatting (pre-commit-hooks)

  • trailing-whitespace: Removes trailing whitespace from lines
  • end-of-file-fixer: Ensures files end with a newline
  • check-yaml: Validates YAML syntax (e.g., Taskfile.yml, .pre-commit-config.yaml)
  • check-json: Validates JSON syntax (excludes .vscode/extensions.json)
  • check-merge-conflict: Detects merge conflict markers
  • check-added-large-files: Prevents files >1MB from being committed

Pre-commit Tasks

Run checks on all files

task pre-commit:run
Use this to see all violations in the project before committing.

Update hooks to latest versions

task pre-commit:update
Periodically run this to keep pre-commit hooks up to date.

Install/Uninstall hooks

task pre-commit:install    # Install git hook
task pre-commit:uninstall  # Remove git hook (keeps config)

How It Works

When you attempt to commit:

  1. Pre-commit hooks run automatically
  2. If any hook fails:
  3. The commit is blocked
  4. Files may be automatically fixed (trailing whitespace, EOF)
  5. You must review the changes and stage them again
  6. If all hooks pass, the commit proceeds

Example Workflow

# Stage your changes
git add .

# Attempt to commit
git commit -m "feat(detector): add new detection mode"

# If hooks fail:
# 1. Review the output
# 2. Fix any issues (some are automatic)
# 3. Stage the fixed files: git add .
# 4. Retry: git commit -m "feat(detector): add new detection mode"

If absolutely necessary, you can skip pre-commit hooks:

git commit --no-verify -m "message"

However, this is discouraged as it bypasses important quality checks.

Configuration

.pre-commit-config.yaml

Defines which hooks run and their configuration.

.markdownlintrc.json

Configuration for markdown linting (line length limits, etc.)

.markdownlintignore

Excludes directories with intentionally long lines (specs/, .specify/, .claude/)

Troubleshooting

Hook fails with "command not found"

Make sure dependencies are installed: 

task env:setup

"commitizen" hook keeps failing on commit messages

Check the message format: type(scope): description

Valid examples: - feat(wifi): implement AP mode - fix(detector): correct GPIO pin mapping - docs(claude): update setup instructions - refactor(serial): simplify protocol handling

See Build & Upload for recommended commit scopes.

Files keep getting modified by end-of-file-fixer

This is expected — the hook automatically adds missing newlines. Stage the changes and retry the commit.

Large file rejected by check-added-large-files

The limit is 1MB. If you need to add a large file:

  1. Consider if it should be in git (binaries and large data files should use Git LFS)
  2. Or modify .pre-commit-config.yaml to increase the limit (not recommended)

See Also