Developer Setup and Hook Installation

Poriscope provides a helper script to install and maintain local Git hooks used for quality control and post-merge automation.

This setup is intended for Poriscope users who want to become contributors or developers.

Overview

The setup script performs two key tasks:

  1. Installs and activates pre-commit hooks for quality control

  2. Installs a post-merge Git hook that automates environment maintenance

These hooks work together to ensure that:

  • Code quality checks run before commits

  • Developer environments stay synchronized after pulls and merges

What the Setup Script Does

When executed, the setup script:

  • Detects the repository root using git rev-parse --show-toplevel

  • Installs the pre-commit Python package (if missing)

  • Uninstalls any existing pre-commit hooks

  • Reinstalls pre-commit hooks using the repository configuration

  • Copies the project’s post-merge hook into .git/hooks/

  • Marks the post-merge hook as executable

  • Sets gitflow.prefix.versiontag to v, so git flow release finish <version> tags the release v<version>

The script is safe to run multiple times.

Running the Setup Script

From the repository root, run:

python scripts/setup_hooks.py

This command installs both the pre-commit and post-merge hooks locally, and sets the git flow release tag prefix.

Note

The release tag prefix matters because the CD workflow (.github/workflows/release.yml) triggers on tags matching v*. git flow leaves gitflow.prefix.versiontag empty by default, which would tag a release 1.7.0 rather than v1.7.0 and so miss that trigger. Like git hooks, git config is local to each clone, which is why the setup script sets it rather than the repository carrying it.

Note

Git hooks are local to each clone and are not version-controlled. Each developer must run this setup script at least once.

Quality Control via Pre-commit

After installation, the following checks run automatically on every commit:

  • Black – automatic code formatting

  • Ruff – linting and safe auto-fixes

  • Mypy – static type checking

  • check-added-large-files – prevents committing large files

If any check fails, the commit is blocked.

For full details, see:

Quality Control and Developer Workflow

Post-merge Automation

After a successful git pull or git merge, the post-merge hook runs automatically.

It performs tasks such as:

  • Updating Python dependencies when requirements.txt changes

  • Regenerating autodoc and Sphinx documentation

  • Building native wavelet libraries when required

For a detailed explanation of this automation, see:

Post-merge Automation

Using GitHub Desktop

If a pre-commit check fails, GitHub Desktop blocks the commit and displays the error output.

Troubleshooting

If hooks do not appear to run:

  • Re-run the setup script

  • Verify that .git/hooks/pre-commit and .git/hooks/post-merge exist

  • Confirm that Python is available in your PATH

Summary

  • Run the setup script once per clone

  • Pre-commit enforces quality before commits

  • Post-merge keeps environments synchronized

  • Both hooks improve reliability and onboarding

This setup is strongly recommended for all Poriscope developers.

Extra: Disabling Git Hooks

To disable pre-commit hooks locally:

pre-commit uninstall

Pre-commit hooks can be re-enabled with:

pre-commit install

To disable the post-merge hook, rename or remove the hook file:

mv .git/hooks/post-merge .git/hooks/post-merge.disabled

The hook can be restored by reversing this change or by re-running the setup script:

python scripts/setup_hooks.py