zerv

Dynamic versioning from git. Every commit gets its version. Keep semantic-release on main. Let zerv prerelease every other branch.

Documentation: zerv.wisl.dev

Why zerv?

• Runs next to semantic-release - semantic-release decides releases on main; zerv versions every other build: any commit on any branch, even with uncommitted changes. No build is ever unversioned.
• Two modes - zerv flow automates pre-release management from Git branch patterns; zerv version gives full manual control with schemas, overrides, and templates.
• Any output format - SemVer, PEP440, CalVer, or Tera templates. Generate every format your pipelines need from a single ZERV RON payload.

See how zerv compares to semantic-release, setuptools-scm, dunamai, and git describe in Why zerv.

Installation

# Python (uv) - Recommended
uv tool install zerv-version

# Python (pip)
pip install zerv-version

# Rust (cargo)
cargo install zerv

# Installation script (latest, or `bash -s vX.X.X` for a specific version)
curl -sSL https://raw.githubusercontent.com/wislertt/zerv/main/scripts/install.sh | bash

# Pre-built binaries
# https://github.com/wislertt/zerv/releases

The PyPI wheel also exposes a Python binding: import zerv.

Quick Start

Version any Git state: zerv flow generates meaningful SemVer versions from any Git state, no manual configuration required.

# The current branch determines the output
zerv flow
# → 1.0.0 (on main branch with tag v1.0.0)
# → 1.0.1-rc.1.post.3 (on release branch with pre-release tag)
# → 1.0.1-beta.1.post.3+develop.3.gf297dd0 (on develop branch)
# → 1.0.1-alpha.59394.post.1+feature.new.auth.1.g4e9af24 (on feature branch)
# → 1.0.1-alpha.17015.post.1.dev.1764382150+feature.dirty.work.1.g54c499a (on dirty feature branch)

Fan one ZERV RON payload out to every format your pipelines need in the quickstart.

Documentation

Full documentation lives at zerv.wisl.dev:

• Why zerv - positioning vs semantic-release, setuptools-scm, dunamai, git describe
• Quickstart - one ZERV RON payload to every format
• Concepts - flow, version, schema system, formats and templates, config file
• CI/CD - GitHub Actions usage, coexisting with semantic-release
• CLI reference - zerv version, zerv flow, zerv check, zerv render
• Python binding - import zerv from the PyPI wheel
• Troubleshooting

Development

git clone https://github.com/wislertt/zerv.git
cd zerv

uv tool install bakefile

bake setup-dev        # Install pre-commit hooks and cargo-tarpaulin

bake test             # Full test suite (Docker Git + Docker tests enabled)
bake test-rust        # Rust tests only
bake test-python      # Python binding tests only
bake lint             # Formatting and clippy checks
bake docs             # Local Mintlify docs dev server

The project uses uv and mise for dependency and tool management.

Contributing

Contributions are welcome. See CLAUDE.md for development guidelines, including project structure, testing conventions, and the development workflow.

Author

Wisaroot Lertthaweedech – wisl.dev

License

Licensed under the Apache License 2.0. See LICENSE for the full text.

The wordmark in docs/img/brand/ uses outlined paths from Sora, licensed under the SIL Open Font License 1.1.