Skip to main content

Templates Overview

Versionator uses Mustache templating for flexible version output formatting. Templates can be used with the --template flag and in configuration files.

Basic Usage​

Use {{VariableName}} syntax to insert template variables:

# Simple template
versionator output version -t "{{MajorMinorPatch}}"
# Output: 1.2.3

# With prefix
versionator output version -t "{{Prefix}}{{MajorMinorPatch}}" --prefix
# Output: v1.2.3

# Custom format
versionator output version -t "Version: {{Major}}.{{Minor}}.{{Patch}}"
# Output: Version: 1.2.3

Available Variables​

See Template Variables for the complete list. Common variables include:

VariableDescriptionExample
{{Major}}Major version1
{{Minor}}Minor version2
{{Patch}}Patch version3
{{MajorMinorPatch}}Core version1.2.3
{{Prefix}}Version prefixv
{{ShortHash}}Git short hashabc1234
{{BranchName}}Current branchmain

Pre-release and Metadata​

Pre-release and metadata are rendered from their own templates:

versionator output version \
  -t "{{MajorMinorPatch}}{{PreReleaseWithDash}}{{MetadataWithPlus}}" \
  --prerelease="alpha-{{CommitsSinceTag}}" \
  --metadata="{{BuildDateTimeCompact}}.{{ShortHash}}"
# Output: 1.2.3-alpha-5+20241211103045.abc1234

WithDash and WithPlus Variants​

  • {{PreReleaseWithDash}} includes the leading - (or empty if no pre-release)
  • {{MetadataWithPlus}} includes the leading + (or empty if no metadata)

This makes it easy to build valid SemVer strings:

# Pre-release only
versionator output version -t "{{MajorMinorPatch}}{{PreReleaseWithDash}}" --prerelease="beta"
# Output: 1.2.3-beta

# No pre-release (variable is empty)
versionator output version -t "{{MajorMinorPatch}}{{PreReleaseWithDash}}"
# Output: 1.2.3

Configuration Templates​

Set default templates in .versionator.yaml:

prerelease:
  template: "alpha-{{CommitsSinceTag}}"

metadata:
  template: "{{BuildDateTimeCompact}}.{{ShortHash}}"

Then use without specifying the template:

versionator output version \
  -t "{{MajorMinorPatch}}{{PreReleaseWithDash}}{{MetadataWithPlus}}" \
  --prerelease \
  --metadata

Custom Variables​

Define custom variables in config:

custom:
  AppName: "MyApp"
  Environment: "prod"

Use them in templates:

versionator output version -t "{{AppName}}-{{MajorMinorPatch}}"
# Output: MyApp-1.2.3

Or set inline:

versionator output version -t "{{AppName}}-{{MajorMinorPatch}}" --set AppName="MyApp"

Code Generation​

Templates are also used by the emit command:

# Use built-in Python template
versionator output emit python --output _version.py

# Dump template for customization
versionator output emit dump python > custom_python.tmpl

# Use custom template
versionator output emit --template-file custom_python.tmpl --output _version.py

View Current Values​

See all variables with their current values:

versionator config vars

Template Syntax Reference​

Versionator uses Mustache syntax:

SyntaxDescription
{{var}}Insert variable value
{{#var}}...{{/var}}Section (if var is truthy)
{{^var}}...{{/var}}Inverted section (if var is falsy)
{{! comment }}Comment (not rendered)

Conditional Example​

# Include "dirty" suffix only if there are uncommitted changes
versionator output version -t "{{MajorMinorPatch}}{{#Dirty}}-dirty{{/Dirty}}"
# Output with changes: 1.2.3-dirty
# Output without: 1.2.3

See Also​