Skip to content

Developer Commands

Quick reference for common development commands in this project.

Environment Setup

# Enter the dev environment (creates venv + installs deps automatically)
hatch shell

# Or run commands directly without entering the shell
hatch run <command>

Targeting Specific Environments

Hatch manages multiple environments (default, docs, test matrix). To run commands in a specific environment, prefix with the environment name:

hatch run <cmd>              # → default environment
hatch run docs:<cmd>         # → docs environment
hatch run test.py3.12:<cmd>  # → test.py3.12 environment

Temporary Package Installs

You can install packages temporarily into a Hatch environment for quick experimentation:

hatch run pip install some-package

Warning: This install is temporary — it disappears when the environment is recreated (hatch env remove default). For permanent dependencies, add them to pyproject.toml under [project.optional-dependencies] instead.

Useful for: quick debugging, one-off tools, testing compatibility before committing to a dependency.

Using pip + venv (manual)

# Create virtual environment
python -m venv .venv

# Activate (Windows PowerShell)
.\.venv\Scripts\Activate.ps1

# Activate (macOS/Linux)
source .venv/bin/activate

# Install in editable mode with dev dependencies
pip install -e ".[dev]"

Testing

# Run all tests
hatch run test

# Run with verbose output
hatch run test -v

# Run specific test file
hatch run test tests/unit/test_example.py

# Run with coverage
hatch run test-cov

Multi-Version Testing

Hatch can run tests across multiple Python versions (3.11–3.13) using a test matrix defined in pyproject.toml.

# Run tests on ALL Python versions in the matrix
hatch run test:run

# Run tests with coverage on all versions
hatch run test:cov

# Run on a specific version only
hatch run +py=3.12 test:run

# Show all environments and their matrices
hatch env show

Note: Each Python version in the matrix must be installed on your system. Hatch will skip versions that aren't available locally. CI workflows handle this automatically via actions/setup-python.

Without Hatch (direct commands) 
pytest
pytest -v
pytest tests/unit/test_example.py
pytest --cov=simple_python_boilerplate --cov-report=term-missing

Linting & Formatting

# Check for linting issues
hatch run lint

# Auto-fix linting issues
hatch run lint-fix

# Check formatting
hatch run fmt-check

# Apply formatting
hatch run fmt
Without Hatch (direct commands) 
ruff check .
ruff check --fix .
ruff format --check .
ruff format .

Type Checking

# Run mypy
hatch run typecheck
Without Hatch (direct commands) 
mypy src/
mypy --strict src/

Building

# Build source and wheel distributions
hatch build

# Clean build artifacts
hatch clean
Without Hatch (direct commands) 
pip install build
python -m build

Utility Scripts

# Archive completed TODO items
python scripts/archive_todos.py
# or via task runner
task clean:todo

# Clean build artifacts and caches
python scripts/clean.py
python scripts/clean.py --dry-run
task clean:all

# Print diagnostics bundle for bug reports
python scripts/doctor.py
python scripts/doctor.py --markdown   # For GitHub issues
python scripts/doctor.py --output var/doctor.txt
task doctor

# Environment health check
python scripts/env_doctor.py
task doctor:env

# Git health dashboard
python scripts/git_doctor.py
task doctor:git

# Fetch, prune stale refs, sync tags
task doctor:git:refresh

# Detailed commit report
task doctor:git:commits

# All health checks in one report
task doctor:all

# One-command setup for fresh clones
python scripts/bootstrap.py
task bootstrap

GitHub Actions Version Management

Manage SHA-pinned GitHub Actions across workflow files.

# Show all pinned actions with version info
python scripts/workflow_versions.py show
task actions:versions

# Show offline (skip GitHub API)
task actions:versions -- --offline

# JSON output (useful for scripting)
task actions:versions -- --json

# Filter results (stale, upgradable, no-desc, or all)
task actions:versions -- --filter stale
task actions:versions -- --filter upgradable

# Quiet / CI mode (exit 1 if stale or upgradable actions found)
task actions:versions -- --quiet

# CI gate shortcut (same as --quiet, for pre-push hooks or CI)
task actions:check

# Update version comments and add descriptions
python scripts/workflow_versions.py update-comments
task actions:update-comments

# Upgrade all actions to their latest release
python scripts/workflow_versions.py upgrade
task actions:upgrade

# Preview upgrades without modifying files
task actions:upgrade:dry-run

# Upgrade a specific action
task actions:upgrade -- actions/checkout

# Upgrade to a specific version
task actions:upgrade -- actions/checkout v6.1.0

# Force colored output
task actions:versions -- --color

Tip: Set GITHUB_TOKEN for higher API rate limits (5,000/hr vs. 60/hr). The remaining rate limit is shown at the end of each run.

API responses are cached on disk (.cache/workflow-versions/, 1-hour TTL). Set WV_CACHE_TTL=0 to disable caching.

Git Shortcuts

# Check status
git status

# Stage all changes
git add .

# Commit with conventional message
git commit -m "feat: add new feature"

# Push to remote
git push origin <branch-name>

Pre-commit (if installed)

# Install hooks
pre-commit install

# Run on all files
pre-commit run --all-files

# Update hooks to latest versions
pre-commit autoupdate

See Enabled Hooks

# Inspect the config to see all configured hooks
cat .pre-commit-config.yaml

# Or run all hooks verbosely to see each hook's status
pre-commit run --all-files --verbose

# List raw Git hook scripts
ls .git/hooks/

Disable / Skip Hooks

# Uninstall pre-commit hooks from this repo
pre-commit uninstall

# Skip ALL hooks for a single commit
SKIP=all git commit -m "feat: commit without hooks"
# Windows (PowerShell)
$env:SKIP="all"; git commit -m "feat: commit without hooks"; Remove-Item Env:SKIP

# Skip specific hooks only (comma-separated IDs)
SKIP=mypy,bandit git commit -m "fix: skip slow hooks"
# Windows (PowerShell)
$env:SKIP="mypy,bandit"; git commit -m "fix: skip slow hooks"; Remove-Item Env:SKIP

# Re-enable hooks
pre-commit install

Without pre-commit (raw Git)

# Skip all Git hooks for a single commit
git commit --no-verify -m "feat: bypass all hooks"
# Short form
git commit -n -m "feat: bypass all hooks"

# Disable hooks globally via hooksPath
mkdir -p /tmp/no-hooks
git config core.hooksPath /tmp/no-hooks

# Restore default hooks path
git config --unset core.hooksPath

# Or delete the hook script directly
rm .git/hooks/pre-commit

Quick Checks Before PR

# Run all quality checks (lint, format check, typecheck, test)
hatch run check
Without Hatch (direct commands) 
pytest && ruff check . && ruff format --check . && mypy src/

Hatch Reference

Common hatch commands beyond the project scripts defined above.

# Enter the dev shell (activates the default env)
hatch shell

# Leave the hatch shell
exit

# Show all configured environments and their scripts
hatch env show

# Remove a specific environment (e.g. to reset it)
hatch env remove default

# Remove all environments
hatch env prune

# Build sdist and wheel into dist/
hatch build

# Clean build artifacts
hatch clean

# Show project metadata (name, version, dependencies)
hatch project metadata

# Show resolved version
hatch version

# Show dependency tree
hatch dep show requirements

# Run an arbitrary command inside the default env
hatch run python -c "import sys; print(sys.executable)"

# Run a command in a specific env (if configured)
hatch run <env>:<command>

Full docs: hatch.pypa.io

See Also