How It Works

The version resolution engine follows a deterministic algorithm.

Mode Selection

"Dirty" includes modified tracked files and untracked files (excluding ignored).

Concrete Version

At a clean tagged commit, the engine returns the exact tag:

Tag: v2.3.1
Result: 2.3.1

No pre-release or metadata is added.

Development Version

Between releases, the engine computes a target version:

Priority Order

1. Valid target directive — explicit target: X.Y.Z in commits
2. Absolute sets — version: major: 3 (highest per component)
3. Relative changes — version: major or breaking: (coalesced)
4. Default fallback:
   • Base is pre-release → core unchanged
   • Base is final → patch + 1
   • No base, repo has tags → highest major + 1
   • No tags anywhere → 0.1.0

Build Metadata

Development versions include ordered metadata:

Tag Recognition

Valid Tags

A tag is recognised if:

• It is an annotated tag (lightweight ignored)
• Name is valid SemVer (optional v prefix)
• Pre-release classifiers map to known aliases
• All components are valid integers

Multiple Tags

If multiple valid tags exist on one commit:

• Final release outranks pre-release of same core
• Otherwise, highest SemVer wins

Commit Scanning

Scope

Traversal

• All commits are scanned, including merge commits themselves
• Keywords scanned from all reachable paths (traverses entire merge graph)
• Commit count for metadata uses first-parent only, excluding merges

Ignore Directives

Commits can be excluded from version calculation:

Use case: When merging a PR, use version: ignore-merged in the merge commit to discard all incoming version directives and specify a consolidated directive instead.

Examples