pup-down: Reports Repo Infrastructure Changes That Belong in Templates

Report-only. Compares the active repository's infrastructure against canonical templates and lists the files the repo has moved ahead on that may be worth copying back upstream.

Purpose

Professional Python repositories commonly share infrastructure such as:

• editor and Git configuration
• ignore and line-ending rules
• Markdown, YAML, and link checking
• formatting, linting, type checking, and testing
• documentation tooling
• continuous integration
• package and release validation

pup-down makes it easy to identify infrastructure improvements made during recent work that should possibly be copied back to the canonical templates.

Benefits

pup-down is report-only. Each repository fetches the current baseline and compares it with its own infrastructure. Nothing reaches in from a central place, so:

Repo owner is in control. Run it when you choose. No files are updated. A list of changes to possibly copy to the canonical template files is provided.

Templates are fetched by immutable commit SHA, so an update always reflects the latest push to the template repository and every run is pinned to an exact template commit.

Repo type is inferred from the presence of key files so no extensive configuration is needed. For example:

• ALL REPOS
• pyproject.toml indicates ALL PY REPOS
• pyproject.toml + src indicates ALL PY SRC REPOS

Default Template Source

• templates

Compare a Repo with Templates

# compare with canonical templates
uvx pup-down@latest

# compare using the latest published pup-down version
uvx pup-down@latest

Developer Command Reference

git clone https://github.com/pup-pack/pup-down

cd pup-down
code .

uv self update
uv python pin 3.15

uv python install
uv lock --upgrade
uv sync

uv run pre-commit install
uv run pre-commit autoupdate

git add -A
uv run pre-commit run --all-files
# repeat if changes were made
uv run pre-commit run --all-files

# run locally to test
uv run pup-down

# types, tests, docs
uv run ty check
uv run python -m pytest
uv run python -m zensical build

# save progress
git add -A
git commit -m "update"
git push -u origin main

Documentation

• Documentation

Annotations

.annotations/annotations.md

Citation

CITATION.cff

License

MIT