Version calculation algorithm

GitVersion gathers candidate versions from enabled strategies and selects the highest incremented semantic version. Several strategies can contribute to one calculation. The order of entries in strategies does not define their priority.

This page expands how versions are calculated into decision diagrams. A workflow supplies defaults, a strategy supplies a candidate, and a deployment mode processes the selected candidate. Read each scenario together with its effective configuration.

For the established v7 CLI, run gitversion config validate --config GitVersion.yml before calculating a version. This checks configuration structure, property values, regular expressions, and branch configuration references without accessing a Git backend. Validation does not calculate candidates or prove release-policy outcomes; inspect the effective configuration and calculate over representative history too.

On this page

Calculation overview

flowchart TD
    Context["Current commit, branch and configuration"] --> Config["Resolve branch configuration"]
    Config --> Tagged{"Matching current-commit tag,
resolved increment and
prevent increment when tagged?"} Tagged -->|Yes| TagResult["Use tag and build metadata"] Tagged -->|No| Inherit["Resolve effective configurations
including branch inheritance"] Inherit --> Candidates["Collect and increment strategy candidates"] Candidates --> Any{"Any accepted candidates?"} Any -->|No| Error["No base versions: error"] Any -->|Yes| Select["Select maximum incremented SemVer
Resolve ties and count source"] Select --> InheritedTag{"Inherited increment resolved;
matching current tag and
prevent increment when tagged?"} InheritedTag -->|Yes| TagResult InheritedTag -->|No| Mode["Apply deployment mode"] Mode --> Floor["Raise numeric version if
an eligible branch tag is higher"] Floor --> Result["Semantic version and source metadata"] TagResult --> Result Result --> Output["Version variables and output formatting"]

A tag on the current commit can determine the result when it matches the branch-label rules and the configuration prevents incrementing tagged commits. When the branch increment requires inheritance, GitVersion resolves candidate configurations before repeating this tag check with the selected configuration.

Otherwise, GitVersion collects candidates, compares their incremented versions, resolves source metadata, and applies deployment behavior. The final numeric version cannot be lower than the eligible branch tag selected by the final tag check. This check compares major, minor, and patch without the prerelease label. It can update semantic provenance while retaining the counting anchor.

An empty branch history or a calculation with no accepted base candidates produces an error. Output formatting happens after version calculation.

All calculation strategies

flowchart TD
    Config["One effective configuration"] --> Strategies["Evaluate enabled non-fallback strategies"]
    Strategies --> Configured["ConfiguredNextVersion
Configured next-version"] Strategies --> Tagged["TaggedCommit
Eligible tags"] Strategies --> Merge["MergeMessage
Release merge messages"] Strategies --> Name["VersionInBranchName
Release branch name"] Strategies --> Release["TrackReleaseBranches
Related release targets"] Strategies --> Mainline["Mainline
Commit and merge traversal"] Configured --> Filter["Ignore filters and candidate increment"] Tagged --> Filter Merge --> Filter Name --> Filter Release --> Filter Mainline --> Filter Filter --> Any{"Any accepted candidate
from these strategies?"} Any -->|Yes| Pool["Add candidates to global comparison"] Any -->|No| Enabled{"Fallback enabled?"} Enabled -->|Yes| Fallback["Fallback candidate:
apply filters and increment"] Fallback --> Pool Enabled -->|No| None["No candidate from this configuration"]

The branches in this diagram represent independent candidate producers. They do not imply parallel execution or a priority order. Each strategy checks its enabled flag and eligibility conditions. GitVersion applies candidate ignore filters before adding a candidate to the comparison.

Strategy When it can contribute Candidate evidence
ConfiguredNextVersion next-version exists, parses, and matches branch-label rules. The configured version, with its label operation; this is an external semantic source.
TaggedCommit The tag service finds eligible semantic versions. Tags selected according to prefix, format, label, history, and branch tracking; configured and message-derived increments apply.
MergeMessage Merge-message tracking is enabled and a parsable message supplies a version from a configured release branch. The version and message commit; the merged-branch prevent-increment setting controls its increment.
VersionInBranchName The effective configuration describes a release branch, and the current or inherited branch name contains a version. The branch-name version and label, with no explicit numeric increment; this is an external semantic source.
TrackReleaseBranches The branch tracks releases, and a related release has a target version and a merge base with the current branch. A version in the release name, or an eligible prerelease tag on the release's own history; the current branch's increment applies.
Mainline Mainline is enabled. A candidate calculated by traversing commit, tag, branch, and merge history.
Fallback It is enabled and no other strategy produced an accepted candidate for this effective configuration. A starting version with an increment derived from effective configuration and relevant commit messages.

TrackReleaseBranches prefers a versioned release name. Its tag alternative examines the release's first-parent history while excluding main's first-parent history. It treats the target as a stable numeric version before calculating the tracking branch's increment.

Fallback is considered separately for each effective configuration. It is not an unconditional final version of 0.1.0. If every candidate is excluded or no enabled strategy can produce one, calculation fails.

See calculation strategies for source semantics and configuration for the tracking and ignore controls.

Branch inheritance

flowchart TD
    Branch["Branch configuration"] --> Inherit{"Increment is Inherit?"}
    Inherit -->|No| Effective["Effective configuration"]
    Inherit -->|Yes| PR{"Allowed pull-request target
identified from merge context?"} PR -->|Yes| Target["Use target as source branch"] PR -->|No| Sources["Find allowed source branches"] Sources --> Found{"Source branches found?"} Found -->|Yes| Recursive["Recursively inherit configuration
with cycle guard"] Target --> Recursive Recursive --> Results["Zero, one or multiple
effective configurations"] Found -->|No| Global{"Global increment is Inherit?"} Global -->|Yes| Skip["Skip orphaned branch"] Global -->|No| Fallback["Use global fallback configuration"] Effective --> Results Fallback --> Results

An explicit branch increment produces an effective configuration directly. Inherit follows allowed source branches and combines their configuration with the child branch's settings. A recognized pull-request target can supply this inheritance source. The traversal guards against cycles.

Several possible sources can produce several effective configurations. Their strategy candidates enter the same version comparison. An orphaned branch is skipped when the global increment also requires inheritance; otherwise global fallback configuration supplies the remaining settings.

Candidate increments

Each candidate carries a base version, source information, and an increment operation. Strategies using the shared increment finder follow these rules:

  1. Select the relevant history between the candidate source and current commit. Apply ignore rules and omit history already covered by eligible version tags.
  2. Apply the commit-message mode: disabled, enabled, or merge messages only.
  3. Within a message, check no-bump, major, minor, and patch patterns in that order. Combine the increments across the selected commits. A matching version-bump reset changes accumulation and ends the scan at that point.
  4. Use the branch increment when no message override supplies one and an increment is requested. The branch increment normally sets the minimum; reset behavior can override that minimum.
  5. Apply the candidate's label, force-increment, and alternative-version rules.

Some strategies explicitly supply an increment of None. Mainline also folds its own traversal operations. A no-bump message is therefore not a universal instruction to suppress every strategy's operation. See version increments for the configurable controls.

Select the version and its sources

flowchart TD
    Pool["All accepted incremented candidates"] --> Maximum["Find maximum SemVer"]
    Maximum --> Tie{"Multiple source-backed candidates
produce this same version?"} Tie -->|Yes| Latest["Latest source timestamp chooses
winner and count source"] Tie -->|No| Winner["Keep maximum semantic candidate"] Winner --> Stable{"Winning version is stable?"} Stable -->|Yes| Exclude["Exclude prerelease baselines
from count-source search"] Stable -->|No| Count["Prefer source-backed candidate:
highest incremented version,
then latest source timestamp"] Exclude --> Count Count --> Found{"Source-backed candidate found?"} Found -->|Yes| Anchor["Use its source as counting anchor"] Found -->|No| External["Use highest remaining external candidate:
null counting anchor"] Latest --> Resolved["Resolved semantic and counting sources"] Anchor --> Resolved External --> Resolved

GitVersion compares the incremented candidates using semantic-version ordering. When several candidates with source commits produce the same maximum version, the latest source timestamp selects the candidate and counting source.

Otherwise, the semantic winner remains the maximum candidate, while the count-source search prefers a candidate with a source commit, ordered by incremented version and then source timestamp. For a stable winning version, this search excludes prerelease baselines. If no source-backed candidate remains, the highest remaining external candidate supplies a null counting anchor.

The semantic source explains where the version came from. The commit-count source anchors counting through the Git graph. They can differ: a configured version can supply the semantic baseline while a tag supplies the counting anchor. A null anchor counts all reachable, non-ignored history. Counting is not a count of builds or a first-parent distance.

Use the SemVerSource* and CommitCountSource* variables to inspect these sources. In a candidate trace, keep these fields separate:

Field What it explains
Strategy and effective branch Which rules produced the candidate.
Base version and semantic source Which tag, message, branch name, configuration value, or traversal supplied the version.
Increment and incremented version Which operation was applied and which value entered the comparison.
Counting source Which commit anchors the history count.
Outcome Selected, lower version, filtered, disabled, ineligible, fallback skipped, or error.

Mainline traversal

flowchart TD
    Enabled["Mainline enabled"] --> Tags["Gather eligible tags and branch context"]
    Tags --> Traverse["Traverse commits;
inspect branch points and merges"] Traverse --> State["Build commit state and recursive iterations"] State --> Pre["Enrich version and increment context"] Pre --> Rules["Apply matching trunk/non-trunk rules"] Rules --> Post["Clean up context after each commit"] Post --> Fold["Fold baseline operands
and increment operators"] Fold --> Candidate["Mainline candidate enters shared selection"] Traverse --> Unsupported["Recognized merge between two main branches:
currently unsupported"]

Mainline gathers tags and branch context, builds recursive iterations for history, and applies matching commit rules. Those rules produce baseline operands and increment operators, which are folded into a candidate for the shared selection process.

The rule families distinguish these events on trunk/main and non-trunk branches:

Event Trunk/main Non-trunk
Ordinary commit Direct-commit rule. Direct-commit rule.
Stable tag Tagged-commit and last-commit rules. Tagged-commit and last-commit rules.
Prerelease tag Tagged-commit and last-commit rules. Tagged-commit and last-commit rules.
Merge Merge and last-merge rules. Merge and last-merge rules.
Branch point Branching to trunk or non-trunk. Branching to trunk or non-trunk.
First release commit No dedicated trunk rule. Dedicated first-release-commit rule.

These event families do not imply one fixed bump for each event. Tags, configuration, accumulated context, and commit messages determine which operations apply.

A recognized merge between two branches configured as main branches currently has an unsupported path in Mainline. A current-commit tag shortcut can bypass that traversal. The merged-commit helper also rejects a merge with multiple source parents. Include these failure paths when investigating a history.

All deployment modes

flowchart TD
    Candidate["Selected candidate and resolved sources"] --> Mode{"Deployment mode"}
    Mode -->|ManualDeployment| Manual["Keep candidate prerelease state
Attach build metadata"] Mode -->|ContinuousDelivery| Numbered{"Numbered prerelease present?"} Numbered -->|No| Error["Error: prerelease tag required"] Numbered -->|Yes| Delivery["Prerelease number +=
commits since source - 1
Record source distance"] Mode -->|ContinuousDeployment| Deployment["Remove prerelease tag
Record source distance"] Manual --> Floor["Check eligible branch-tag numeric version floor"] Delivery --> Floor Deployment --> Floor
Mode Processing after candidate selection
ManualDeployment Preserves the candidate's prerelease state and attaches build metadata.
ContinuousDelivery Requires a numbered prerelease; adds commits since the counting source minus one to that number and records source distance.
ContinuousDeployment Removes the prerelease tag and records source distance.

Tagged-commit shortcuts use their own metadata handling and bypass this normal dispatch. ContinuousDeployment removes the tag's prerelease component there as well. In the normal path, the branch-tag numeric floor follows mode processing.

Versioning scenario map

These dimensions describe the scenario families across the calculation. They combine: the branch name alone does not choose a strategy. Arbitrary Git histories and custom configurations create more combinations than any finite example catalogue can enumerate.

Dimension Scenarios
Workflow GitFlow, GitHubFlow, trunk-based, custom defaults, switching workflows, and Mainline strategy combinations.
Branch role Main, develop, feature, release, hotfix, support, pull request, and other branches; feature branches originating from releases.
Inheritance Explicit increment, one or several source branches, PR target, orphaned branch, and a branch without unique commits.
Repository context Local and remote refs, worktrees, tag checkout, detached context, and historical commits.
Version evidence Configured version, branch-name version, merge message, stable tag, prerelease tag, competing evidence, and fallback.
Tag tracking Current commit, ancestor, merge target, main or release branch; prefix, format, label compatibility, and ignored evidence.
Release tracking Versioned name, unversioned release with eligible prerelease tag, several releases, missing merge base, and main-history tag exclusion.
Topology Linear commits, branch points, fast-forward, merge commits, nested or repeated merges, reverse merges, deleted source refs, and unsupported merge shapes.
Increment None, Patch, Minor, Major, Inherit, message modes, no-bump, bump reset, already-tagged history, and prevent-increment controls.
Label Stable, prerelease, branch-derived or SHA labels; matching and mismatching labels and numeric prerelease identifiers.
Ignore Commit SHA, date, path, and reference controls affecting discovery, inheritance, or counting.
Selection One or several strategies/configurations, equal-version ties, distinct semantic/count sources, skipped fallback, and no candidate.
Finalization All three deployment modes, source distance, higher branch-tag floor, provenance, and output formatting.
Failure Empty history, no accepted candidates, invalid version/configuration, delivery without numbered prerelease, and unsupported merges.

The GitFlow examples, GitHubFlow examples, and trunk-based examples show histories with asserted versions. The integration scenarios and calculation tests provide the larger executable catalogue.

Executable checkpoints

These histories are generated by tests that assert the displayed versions. The calculation examples also assert the semantic source, counting source, and distance. They provide representative checkpoints for the rules above; the algorithm flowcharts themselves remain authored diagrams.

Competing candidates

With GitHubFlow defaults, a configured next-version of 5.0.0 wins over the incremented 1.0.0 tag. It supplies an external semantic source, while the tag remains the counting source. Lowering next-version to 0.5.0 makes the tag candidate win instead.

sequenceDiagram
    main->>main: commit
    main->>main: tag 1.0.0
    main->>main: commit
    rect rgb(211, 211, 211)
        Note over main: 5.0.0-1
    end
    Note over main: next-version: 5.0.0

sequenceDiagram
    main->>main: commit
    main->>main: tag 1.0.0
    main->>main: commit
    rect rgb(211, 211, 211)
        Note over main: 1.0.1-1
    end
    Note over main: next-version: 0.5.0

Inherited increments

These GitHubFlow examples set the feature branch increment to Inherit. Changing its source branch main from Patch to Minor changes the feature version from 1.0.1-work.1+1 to 1.1.0-work.1+1.

sequenceDiagram
    main->>main: commit
    main->>main: tag 1.0.0
    create participant feature_work as feature/work
    main->>feature_work: branch from main
    feature_work->>feature_work: commit
    rect rgb(211, 211, 211)
        Note over feature_work: 1.0.1-work.1+1
    end
    Note over feature_work: main increment: Patch#59; feature increment: Inherit

sequenceDiagram
    main->>main: commit
    main->>main: tag 1.0.0
    create participant feature_work as feature/work
    main->>feature_work: branch from main
    feature_work->>feature_work: commit
    rect rgb(211, 211, 211)
        Note over feature_work: 1.1.0-work.1+1
    end
    Note over feature_work: main increment: Minor#59; feature increment: Inherit

Equal versions and separate sources

The tie example supplies two controlled strategy candidates of 2.0.0, anchored at consecutive commits in a real repository. It isolates selection from strategy discovery: the latest commit supplies both sources, leaving one commit to count. ManualDeployment produces 2.0.0+1.

sequenceDiagram
    main->>main: commit
    main->>main: tag 1.0.0
    Note over main: Controlled candidate A: 2.0.0 at this commit
    main->>main: commit
    Note over main: Controlled candidate B: 2.0.0 at this later commit
    main->>main: commit
    Note over main: Equal candidates: 2.0.0 at tag commit and next commit#59; latest source wins
    rect rgb(211, 211, 211)
        Note over main: 2.0.0+1
    end

In the GitFlow release merge below, the merge message supplies 2.0.0. The older 1.0.0 tag supplies the counting source. The release commit, merge commit, and following main commit all count, giving a distance of three.

sequenceDiagram
    main->>main: commit
    main->>main: tag 1.0.0
    create participant release_2_0_0 as release/2.0.0
    main->>release_2_0_0: branch from main
    release_2_0_0->>release_2_0_0: commit
    release_2_0_0->>main: merge
    main->>main: commit
    rect rgb(211, 211, 211)
        Note over main: 2.0.0-3
    end

Deployment modes on the same history

Each example uses GitHubFlow with the main branch label set to beta and the named deployment mode. Two commits after 1.0.0 give the same semantic source, patch increment, and counting distance in all three modes.

Mode Asserted full version
ManualDeployment 1.0.1-beta.1+2
ContinuousDelivery 1.0.1-beta.2
ContinuousDeployment 1.0.1
sequenceDiagram
    main->>main: commit
    main->>main: tag 1.0.0
    main->>main: commit
    main->>main: commit
    rect rgb(211, 211, 211)
        Note over main: 1.0.1-beta.1+2
    end

sequenceDiagram
    main->>main: commit
    main->>main: tag 1.0.0
    main->>main: commit
    main->>main: commit
    rect rgb(211, 211, 211)
        Note over main: 1.0.1-beta.2
    end

sequenceDiagram
    main->>main: commit
    main->>main: tag 1.0.0
    main->>main: commit
    main->>main: commit
    rect rgb(211, 211, 211)
        Note over main: 1.0.1
    end

Tags and commit messages

These trunk-based examples check tag shortcuts and commit-message increments.

sequenceDiagram
    activate main
    main->>main: commit
    main->>main: tag 1.2.0
    rect rgb(211, 211, 211)
        Note over main: 1.2.0
    end
    main->>main: commit
    rect rgb(211, 211, 211)
        Note over main: 1.2.1
    end
    main->>main: commit
    rect rgb(211, 211, 211)
        Note over main: 1.2.2
    end
    main->>main: tag v1.2.2
    rect rgb(211, 211, 211)
        Note over main: 1.2.2
    end
    main->>main: commit
    rect rgb(211, 211, 211)
        Note over main: 1.2.3
    end

sequenceDiagram
    activate main
    main->>main: commit
    main->>main: tag 1.2.0
    rect rgb(211, 211, 211)
        Note over main: 1.2.0
    end
    main->>main: Commit 'Fix a bug +semver: patch'
    rect rgb(211, 211, 211)
        Note over main: 1.2.1
    end
    main->>main: Commit 'Add an API +semver: minor'
    rect rgb(211, 211, 211)
        Note over main: 1.3.0
    end
    main->>main: Commit 'Break an API +semver: major'
    rect rgb(211, 211, 211)
        Note over main: 2.0.0
    end
    main->>main: commit
    rect rgb(211, 211, 211)
        Note over main: 2.0.1
    end

Diagram maintenance

These algorithm flowcharts are authored Mermaid sources in docs/diagrams, included in the page with the same renderer and shared theme as the workflow examples. The existing syntax validator checks all .mmd files:

node docs/scripts/validate-mermaid.mjs

The GenerateMermaidSources task regenerates test-derived DocumentationSamplesFor*.mmd scenario diagrams; it leaves these algorithm flowcharts intact. See contributing examples when changing a worked history and its asserted versions.

The implementation entry points for maintaining this map are candidate calculation, configuration inheritance, increment selection, and Mainline traversal. Update the diagram and accompanying explanation when those decision rules change.