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.
