Skip to main content
Once a schema has assembled the version, zerv renders it into an output format, or through a Tera template for anything else.

​
Output formats

  • semver - 1.0.1-alpha.17015.post.1.dev.1764382150+feature.dirty.work.1.g54c499a
  • pep440 - 1.0.1a17015.post1.dev1764382150+feature.dirty.work.1.g54c499a (Python)
  • zerv - the internal RON representation, used for piping between commands

​
Piping with ZERV RON

The zerv format is both an output and an input: emit it once, then re-render it any number of times. Upstream must output --output-format zerv for stdin piping to work.
The RON payload is the fully-resolved version: schema and variables together.

​
Fan out to every format

Docker wants +-free tags, PyPI wants PEP440, releases want v-prefixed SemVer. Generate ZERV RON once and re-render the same payload for each consumer: VCS detection runs once, every conversion is a pure re-render, and every artifact carries a version derived from one resolved state.
The Quickstart shows the full set, including schema-based v_major and v_major_minor tags.

​
Templates

--output-template renders through the Tera templating engine, with conditionals, filters, and zerv-provided functions.

​
Template variables

Core version fields:
  • major, minor, patch - version numbers
  • epoch - epoch version (optional)
  • post, dev - post-release and dev identifiers
Pre-release context:
  • pre_release.label - pre-release type (“alpha”, “beta”, “rc”)
  • pre_release.number - pre-release number
  • pre_release.label_code - short code (“a”, “b”, “rc”)
  • pre_release.label_pep440 - PEP440 format (“a”, “b”, “rc”)
VCS/metadata fields:
  • distance - commits from reference point
  • dirty - working directory dirty state
  • bumped_branch - branch name
  • bumped_commit_hash - full commit hash
  • bumped_commit_hash_short - short commit hash
  • bumped_timestamp - commit timestamp
  • last_commit_hash - last tag commit hash
  • last_commit_hash_short - short last tag commit hash
  • last_timestamp - last tag timestamp
Parsed version objects:
  • semver_obj.base_part - “1.2.3”
  • semver_obj.pre_release_part - “alpha.1.post.3.dev.5”
  • semver_obj.build_part - “build.456”
  • semver_obj.docker - “1.2.3-alpha.1-build.456” (+ → -, safe as a docker tag)
  • pep440_obj.base_part - “1.2.3”
  • pep440_obj.pre_release_part - “a1.post3.dev5”
  • pep440_obj.build_part - “build.456”
Formatted versions:
  • semver - full SemVer string
  • pep440 - full PEP440 string
  • current_timestamp - current Unix timestamp

​
Custom template functions

String manipulation:
  • sanitize(value=variable, preset='dotted') - sanitize with presets: “semver”, “pep440”, “uint”
  • sanitize(value=variable, separator='-', lowercase=true, max_length=10) - custom sanitization
  • prefix(value=variable, length=10) - extract first N characters
  • prefix_if(value=variable, prefix="+") - add prefix only if value not empty
Hashing and formatting:
  • hash(value=variable, length=7) - generate hex hash
  • hash_int(value=variable, length=7, allow_leading_zero=false) - numeric hash
  • format_timestamp(value=timestamp, format="%Y-%m-%d") - format timestamp “2023-12-30”
  • format_timestamp(value=timestamp, format="compact_date") - “20231230”

​
Where to go next

  • GitHub Actions - the reusable workflow that automates this fan-out
  • Render CLI - format conversion for existing version strings