Tag formats

Default formats

If you use either of these, no tagFormat configuration is needed.

Custom formats

The tagFormat field supports {version} and {prefix} placeholders:

tagFormat: "release/v{version}"       # → release/v1.2.0
tagFormat: "{prefix}@{version}"       # → mobile@1.2.0
tagFormat: "{prefix}/release-{version}"

Migrating to a new tag format

Changing tagFormat mid-project can orphan previous tags. There are two layers to be aware of.

legacyTagFormats — recognise old tags automatically

When you switch tagFormat, tags created under the old pattern may no longer match the new one. A common case: you used {prefix}-v{version}-version and switch to {prefix}-v{version}. The old tag app-v1.2.0-version now parses under the new format with a trailing -version suffix, which ReleaseJet treats as a pre-release — so it is skipped during previous-tag detection, and generate aborts asking for --since.

List the old pattern(s) under legacyTagFormats so those tags are still recognised as full releases and previous-tag detection keeps working with no per-run flags:

tagFormat: "{prefix}-v{version}"
legacyTagFormats:
  - "{prefix}-v{version}-version"

A tag that matches a legacy pattern exactly (no leftover suffix) is promoted to a full release; genuine pre-releases (-beta, -rc.1) are still skipped. Each entry must contain {version}, and the field is only honoured when tagFormat is set. Available since 1.25.0.

The orphan-tag safeguard

If a mismatch slips through — the current tag parses but no matching prior tag is found while older tags exist that would have parsed under a previous format — the generate command aborts with an actionable error pointing to the most recent orphan tag and suggesting --since <tag> as a one-off override.

Suffixes

Tags with suffixes (e.g., v1.2.0-beta.1, v1.2.0-rc.0) are supported. ReleaseJet coerces the semver core for comparison; the suffix is preserved in the release name, and such tags are skipped when detecting the previous release.

Note that a tagFormat with a literal after {version} (such as {prefix}-v{version}-version) leaves no room for a suffix: the trailing literal is anchored to the end of the tag, so app-v1.2.0-version-internal will not parse. Prefer a format where {version} comes last (e.g. {prefix}-v{version}); suffixes then work in the usual position — app-v1.2.0-internal, app-v1.2.0-beta, and so on.