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 flowautomates pre-release management from Git branch patterns;zerv versiongives 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 zervfrom 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.
1 maintainer
Release files for zerv-version 0.8.25
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Built distributions (wheels)
| File | Reset | |||
|---|---|---|---|---|
| zerv_version-0.8.25-py3-none-win_arm64.whl | Python 3 | none | Windows ARM64 | Details |
| zerv_version-0.8.25-py3-none-win_amd64.whl | Python 3 | none | Windows x86-64 | Details |
| zerv_version-0.8.25-py3-none-manylinux_2_39_x86_64.whl | Python 3 | none | Linux glibc 2.39+ x86-64 | Details |
| zerv_version-0.8.25-py3-none-manylinux_2_39_aarch64.whl | Python 3 | none | Linux glibc 2.39+ ARM64 | Details |
| zerv_version-0.8.25-py3-none-macosx_11_0_arm64.whl | Python 3 | none | macOS 11.0+ ARM64 | Details |
| zerv_version-0.8.25-py3-none-macosx_10_12_x86_64.whl | Python 3 | none | macOS 10.12+ x86-64 | Details |
Total release size: 13.0 MB
Release files / zerv_version-0.8.25-py3-none-win_arm64.whl
| Download URL | zerv_version-0.8.25-py3-none-win_arm64.whl |
|---|---|
| Size | 2.1 MB |
| Tags | Python 3 Windows ARM64 |
|
SHA-256 checksum How to use checksums |
3d536c982ef6614b8c0b5a641306fac4ec37e49e9a7c15b907f2087d05fe84bc
|
|
BLAKE2b-256 checksum How to use checksums |
d1496ab1f83073c4b40a895eb20daad6bf81b0940e9119b040bd56aedfe8ecfc
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.12.5 {"installer":{"name":"uv","version":"0.12.5","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":null,"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / zerv_version-0.8.25-py3-none-win_amd64.whl
| Download URL | zerv_version-0.8.25-py3-none-win_amd64.whl |
|---|---|
| Size | 2.2 MB |
| Tags | Python 3 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
e8d52cf73462e5ebee97cc3399f109f1f73810106ddcfe2a325add770e1afb16
|
|
BLAKE2b-256 checksum How to use checksums |
a53bde319a9b6fea16b4c048a0907b92f10d1058bfe9cab110f7a9b0e3e9ca0d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.12.5 {"installer":{"name":"uv","version":"0.12.5","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":null,"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / zerv_version-0.8.25-py3-none-manylinux_2_39_x86_64.whl
| Download URL | zerv_version-0.8.25-py3-none-manylinux_2_39_x86_64.whl |
|---|---|
| Size | 2.3 MB |
| Tags | Linux glibc 2.39+ x86-64 Python 3 |
|
SHA-256 checksum How to use checksums |
860e8aef2a99f8a2432bf313ca70adb6ccef4f5689d4e5319d4ab62f28f27964
|
|
BLAKE2b-256 checksum How to use checksums |
7fbb5e82255d468bdb8ce26b8d8b3cfd78cb23f91789962e891f5b5068573c59
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.12.5 {"installer":{"name":"uv","version":"0.12.5","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / zerv_version-0.8.25-py3-none-manylinux_2_39_aarch64.whl
| Download URL | zerv_version-0.8.25-py3-none-manylinux_2_39_aarch64.whl |
|---|---|
| Size | 2.1 MB |
| Tags | Linux glibc 2.39+ ARM64 Python 3 |
|
SHA-256 checksum How to use checksums |
f376f5005cd6c3b1cdcdc408d1d2db75e854a358dae08676d50835ded6d3f238
|
|
BLAKE2b-256 checksum How to use checksums |
3a7603964b62e5cfeda59a00db0341f60455f23100f56dd20997f60a3d691688
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.12.5 {"installer":{"name":"uv","version":"0.12.5","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / zerv_version-0.8.25-py3-none-macosx_11_0_arm64.whl
| Download URL | zerv_version-0.8.25-py3-none-macosx_11_0_arm64.whl |
|---|---|
| Size | 2.1 MB |
| Tags | Python 3 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
67bb0cbd876cfb7d902a7b35253095e6f9dd636e1967ba352fcadb1cd9bd7f3a
|
|
BLAKE2b-256 checksum How to use checksums |
04f8b3384ea3040c6f8d9cf8a5f85355fc772a1022f6eccdbb19037fb89ad611
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.12.5 {"installer":{"name":"uv","version":"0.12.5","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / zerv_version-0.8.25-py3-none-macosx_10_12_x86_64.whl
| Download URL | zerv_version-0.8.25-py3-none-macosx_10_12_x86_64.whl |
|---|---|
| Size | 2.2 MB |
| Tags | Python 3 macOS 10.12+ x86-64 |
|
SHA-256 checksum How to use checksums |
1f2260173bdc7c54dd6f2cf368a99307e5b969a1f216e2b8ac1d67791a594883
|
|
BLAKE2b-256 checksum How to use checksums |
2bbfe739321cdafbe7a99533f2e254b24d7558d8b0cdb03fa80c19a2c37c549d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.12.5 {"installer":{"name":"uv","version":"0.12.5","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
