PVM — Project Version Manager

PVM is a CLI tool for managing Python project versions using Semantic Versioning 2.0.0. It automates version bumps, changelog generation, and Git tagging, all driven by your pyproject.toml.

Content

• Features
• Installation
• Usage
  • Show the Current Version
  • Predict the Next Version
  • Bump the Version
  • Generate a Changelog
• CLI Reference
• Example Workflows
• Development
• Configuration
• Links
• License

Features

• Semantic Versioning: Bump major, minor, patch, prerelease, and build versions.
• Git Integration: Commit and tag version changes, with optional push.
• Changelog Generation: Automated changelog creation and updating.
• Flexible CLI: Powered by Typer, with rich options.
• Preserves Formatting: Updates pyproject.toml without breaking formatting.

Installation

pip install pvm
# or, with uv
uv pip install pvm

Usage

Show the Current Version

pvm show current

Predict the Next Version

pvm show next

Bump the Version

# Bump patch version (e.g., 1.2.3 → 1.2.4)
pvm bump patch

# Bump minor version and add prerelease
pvm bump minor --prerelease --prerelease-token rc

# Bump to a specific version
pvm bump 2.0.0

# Add build metadata
pvm bump patch --build --build-token build.5

# Bump and tag in Git (with prefix)
pvm bump patch --tag --tag-prefix v

# Bump and generate changelog
pvm bump patch --changelog --changelog-file CHANGELOG.md

Generate a Changelog

pvm changelog --file CHANGELOG.md

CLI Reference

Common Options for bump:

• --final : Force a final version (no prerelease/build)
• --prerelease, -p : Add a prerelease (e.g., alpha, beta, rc)
• --prerelease-token : Set prerelease token (e.g., rc, alpha)
• --build, -b : Add build metadata
• --build-token : Set build metadata token
• --tag, -t : Create a Git tag for the new version
• --tag-prefix : Prefix for tag (default: v)
• --changelog, -c : Generate changelog after bump
• --changelog-file : Path to changelog file

Example Workflows

Bump patch, tag, and update changelog:

pvm bump patch --tag --changelog --changelog-file CHANGELOG.md

Show next prerelease version:

pvm show next --prerelease

Development

Install Dev & Test Dependencies

uv sync --group dev --group test

Run Tests

pytest
# or, for all environments:
tox

Format, Lint, and Type-Check

uv run ruff format .
uv run ruff check --fix --exit-zero
uv run pre-commit run --all-files
uv run mypy .

Configuration

PVM reads and writes the version from your pyproject.toml. You can configure changelog file location and other options in your pyproject.toml.

Links

• Homepage
• Source
• Changelog
• Issues
• Documentation

License

MIT License © Malvin Ndip