Metadata Templates

Build metadata provides additional information about a build without affecting version precedence. Per SemVer, versions differing only in metadata are considered equal for sorting.

Stability Model

Metadata supports two modes controlled by the stable setting:

Dynamic (Default: stable: false)

When stable: false (the default), metadata is generated from template at output time:

# .versionator.yaml
metadata:
  template: "{{ShortHash}}"
  stable: false  # Default

Every time you run emit, ci, or output commands, the template is evaluated:

versionator output version
# Output: 1.0.0+abc1234

# After more commits:
versionator output version
# Output: 1.0.0+def5678

This is ideal for continuous delivery workflows where every build should include current commit information.

Static (stable: true)

When stable: true, metadata is stored in the VERSION file:

# Enable stable mode
versionator config metadata stable true

# Now set a fixed value
versionator config metadata set build.123
# VERSION: 1.0.0+build.123

versionator config metadata set 20241212
# VERSION: 1.0.0+20241212

Clear metadata:

versionator config metadata clear
# VERSION: 1.0.0

Checking Current Mode

versionator config metadata stable
# Output: false (or true)

Template Configuration

Set a default template in .versionator.yaml:

metadata:
  template: "{{BuildDateTimeCompact}}.{{ShortHash}}"
  git:
    hashLength: 12    # For {{MediumHash}}

Then use with the flag:

versionator output version -t "{{MajorMinorPatch}}{{MetadataWithPlus}}" --metadata
# Output: 1.0.0+20241211103045.abc1234

Separator Convention

Metadata components use dots (.) as separators:

# Correct - use dots
metadata:
  template: "{{BuildDateTimeCompact}}.{{ShortHash}}"       # 20241211103045.abc1234
  template: "{{CommitsSinceTag}}.{{ShortHash}}.{{BuildDateUTC}}"  # 42.abc1234.2024-01-15

# Incorrect - don't use dashes for metadata components
metadata:
  template: "{{BuildDateTimeCompact}}-{{ShortHash}}"       # Avoid

The leading plus before metadata is automatically added when using {{MetadataWithPlus}}.

Common Patterns

Timestamp + Hash

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

Result: 1.0.0+20241211103045.abc1234

Build Number + Hash

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

Result: 1.0.0+42.abc1234

Date Only

metadata:
  template: "{{BuildDateUTC}}"

Result: 1.0.0+2024-01-15

CI Build Info

metadata:
  template: "ci.{{BuildNumberPadded}}.{{ShortHash}}"

Result: 1.0.0+ci.0042.abc1234

Long Hash

metadata:
  template: "{{MediumHash}}"
  git:
    hashLength: 12

Result: 1.0.0+abc1234def01

Commands

metadata set

Sets a metadata value. Behavior depends on stability:

When stable: true:

versionator config metadata set build.123
# VERSION: 1.0.0+build.123

When stable: false (default):

versionator config metadata set build.123
# Error: cannot set literal metadata when stable is false
# Use --force to set as template, or set stable to true first

# Force it (sets as template):
versionator config metadata set build.123 --force
# Config: template = "build.123"