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
- All calculation strategies
- Branch inheritance
- Candidate increments
- Select the version and its sources
- Mainline traversal
- All deployment modes
- Versioning scenario map
- Executable checkpoints
- Diagram maintenance
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:
- Select the relevant history between the candidate source and current commit. Apply ignore rules and omit history already covered by eligible version tags.
- Apply the commit-message mode: disabled, enabled, or merge messages only.
- 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.
- 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.
- 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.