Version Formats

🚀Version Formats

Five Strategy Choices

Compare generated tag shapes, release stages, project-file conversion, and existing-tag ordering.

Commandcusty version update

📦Category

Reference

🚀Quick Command

strategy + bump + release modifiers -> version

---

semverpep440commitizendategitcount

---

⚙️

Strategies

5

🏷️

Bump Values

patch, minor, major, auto

🕒

Detected Stages

6

🛡️

Explicit Tag Validator

Stable + lifecycle

Strategy and Format Index

📋Generated Version Families

Property	Type	Description	Default	Required
semver	Semantic version	Supports major, minor, patch, prerelease, development, post-style, and build metadata inputs through Custy's semantic-version helper.	v1.2.3	No
pep440	Python package version	Supports PEP 440 alpha, beta, release candidate, development, post-release, local metadata, and epoch inputs.	1.2.3	No
commitizen	Commit-derived SemVer	Runs cz bump --dry-run --changelog, infers a bump, and is intended to delegate final generation to SemVer.	-	No
date	Calendar version	Uses the current local date and includes the v prefix by default.	vYYYY.MM.DD	No
gitcount	Repository count	Uses the repository's total commit count as the numeric tag body.	v123	No

---

Common Shapes

ℹ️Examples

Final	v1.2.3 or 1.2.3
Alpha	v1.2.3-alpha.1 or 1.2.3a1
Beta	v1.2.3-beta.1 or 1.2.3b1
Release candidate	v1.2.3-rc.1 or 1.2.3rc1
Development	v1.2.3-dev.1 or 1.2.3.dev1
Post release	v1.2.3-post.1 or 1.2.3.post1
Local/build metadata	v1.2.3+linux or 1.2.3+linux
PEP 440 epoch	1!2.0.0; generation supports epoch input, while the basic bridge does not preserve every advanced PEP 440 form.

---

Basic SemVer and PEP 440 Bridge

Supported conversion examples

text

PEP 440              SemVer-style
1.2.3a1       <->      v1.2.3-alpha.1
1.2.3b2       <->      v1.2.3-beta.2
1.2.3rc1      <->      v1.2.3-rc.1
1.2.3.dev1    <->      v1.2.3-dev.1
1.2.3.post1   <->      v1.2.3-post.1
1.2.3+linux   <->      v1.2.3+linux

VersionBridge performs basic conversion for compatible three-part versions. It returns no value for an invalid base and is not a complete implementation of every SemVer or PEP 440 edge case. Review conversions involving epochs, compound suffixes, or unusual local identifiers before writing project files.

---

ℹ️Explicit CLI tags support release lifecycle versions

The shared --tag validator accepts stable three-part versions and Custy's supported alpha, beta, release-candidate, development, post-release, and build/local-metadata forms. A missing v prefix is normalized automatically.

Use SemVer-style values such as v2.0.0-rc.1 or common PEP 440-style values such as 2.0.0rc1. Arbitrary lifecycle names and incomplete forms such as v2.0-rc.1 remain invalid.

⚠️Current Commitizen implementation limitation

Commitizen is an accepted strategy value, but the active delegation currently passes an unsupported keyword to SemverStrategy. Treat this path as a known implementation limitation until the source is corrected and validated.

---

Generation, Conversion, and Sorting Are Separate

• A TagStrategy generates the next value.
• VersionBridge converts compatible representations for project files.
• A TagSorter orders tags already present in Git.
• Commitizen generation produces SemVer-oriented output and therefore does not have a separate existing-tag sorter.
• Supplying an explicit accepted tag bypasses automatic generation.

---

Continue

🚀Related Commands

Commands commonly used together with this command.

Versioning Concept

Understand the lifecycle from selection to project-file application and Git tagging.

Version Strategies

Review user-facing strategy inputs and examples.

Versioning and Tags

Understand explicit tags and local Git reference creation.

Strategy Architecture

Inspect generation, factory, sorter, and bridge responsibilities.