Version Variables

Version variables are quite useful if you need different formats of the version number. Running the gitversion executable in your repository will show you what is available. The following is illustrative output; your values depend on the repository history and effective configuration:

{
    "AssemblySemFileVer": "3.22.11.0",
    "AssemblySemVer": "3.22.11.0",
    "BranchName": "release/3.022.011",
    "BuildMetaData": 88,
    "CommitCountSourceDistance": 7,
    "CommitCountSourceSha": "previous-source-commit-sha",
    "CommitDate": "2021-12-31",
    "CustomVersion": "3.22.11-beta.99",
    "EscapedBranchName": "release-3.022.011",
    "FullBuildMetaData": "99.Branch.release/3.22.11.Sha.28c853159a46b5a87e6cc9c4f6e940c59d6bc68a",
    "FullSemVer": "3.22.11-beta.99+88",
    "InformationalVersion": "3.22.11-beta.99+88.Branch.release/3.022.011.Sha.28c853159a46b5a87e6cc9c4f6e940c59d6bc68a",
    "Major": 3,
    "MajorMinorPatch": "3.22.11",
    "Minor": 22,
    "Patch": 11,
    "PreReleaseLabelName": "beta",
    "PreReleaseLabelNameWithDash": "-beta",
    "PreReleaseNumber": 99,
    "PreReleaseLabel": "beta.99",
    "PreReleaseLabelWithDash": "-beta.99",
    "SemVer": "3.22.11-beta.99",
    "SemVerSourceIncrement": "None",
    "SemVerSourceSemVer": "3.22.11",
    "SemVerSourceSha": null,
    "Sha": "28c853159a46b5a87e6cc9c4f6e940c59d6bc68a",
    "ShortSha": "28c8531",
    "UncommittedChanges": 0,
    "VersionSourceDistance": 7,
    "VersionSourceIncrement": "Minor",
    "VersionSourceSemVer": "3.22.11",
    "VersionSourceSha": "previous-source-commit-sha",
    "WeightedPreReleaseNumber": 1099
}

Each property of the above JSON document is described in the below table.

Property Description
AssemblySemFileVer Suitable for .NET AssemblyFileVersion. Defaults to Major.Minor.Patch.0.
AssemblySemVer Suitable for .NET AssemblyVersion. Defaults to Major.Minor.0.0 to allow the assembly to be hotfixed without breaking existing applications that may be referencing it.
BranchName The name of the checked out Git branch.
BuildMetaData The build metadata, usually representing number of commits since the CommitCountSourceSha. Despite its name, will not increment for every build.
CommitCountSourceDistance Number of non-ignored commits reachable from HEAD but not from the counting anchor. A null anchor counts all reachable history.
CommitCountSourceSha SHA of the counting anchor, or JSON null when counting all reachable history.
CommitDate The ISO-8601 formatted date of the commit identified by Sha.
CustomVersion A custom version configured with custom-version-format. Empty when no format is configured.
EscapedBranchName Equal to BranchName, but with / replaced with -.
FullBuildMetaData The BuildMetaData suffixed with BranchName and Sha.
FullSemVer The full, SemVer 2.0 compliant version number.
InformationalVersion Suitable for .NET AssemblyInformationalVersion. Defaults to FullSemVer suffixed by FullBuildMetaData.
Major The major version. Should be incremented on breaking changes.
MajorMinorPatch Major, Minor and Patch joined together, separated by ..
Minor The minor version. Should be incremented on new features.
Patch The patch version. Should be incremented on bug fixes.
PreReleaseLabelName The name of the pre-release label, without the PreReleaseNumber.
PreReleaseLabelNameWithDash The pre-release label name prefixed with a dash.
PreReleaseNumber The pre-release number.
PreReleaseLabel The full pre-release label, including the PreReleaseNumber when present.
PreReleaseLabelWithDash The pre-release label prefixed with a dash.
SemVer The semantic version number, including PreReleaseLabelWithDash for pre-release version numbers.
SemVerSourceIncrement Final increment relative to the semantic baseline: None, Patch, Minor, or Major.
SemVerSourceSemVer Baseline version supplied by the selected artifact or derivation. Mainline may use a folded baseline rather than a literal tag value.
SemVerSourceSha SHA associated with the semantic source; JSON null for external sources such as configuration or a branch name.
Sha The SHA of the Git commit.
ShortSha The Sha limited to 7 characters.
UncommittedChanges The number of uncommitted changes present in the repository.
VersionSourceDistance Compatibility alias for CommitCountSourceDistance.
VersionSourceIncrement Legacy increment metadata, preserved for compatibility. Prefer SemVerSourceIncrement; the legacy field can be None even when an increment was applied.
VersionSourceSemVer Legacy semantic baseline. It need not correspond to VersionSourceSha; prefer SemVerSourceSemVer.
VersionSourceSha Legacy counting-anchor SHA. Prefer CommitCountSourceSha, which represents an absent anchor as null.
WeightedPreReleaseNumber A summation of branch specific pre-release-weight and the PreReleaseNumber. Can be used to obtain a monotonically increasing version number across the branches.

Depending on how and in which context GitVersion is executed (for instance within a supported build server), the above version variables may be exposed automatically as environment variables in the format GitVersion_FullSemVer.

Semantic and counting sources

The semantic source and counting anchor can differ. With a 1.0.0 tag followed by one commit and calculation.next-version: 5.0.0, the semantic baseline is 5.0.0 and SemVerSourceSha is null, while CommitCountSourceSha points to the 1.0.0 tag and CommitCountSourceDistance is 1. A release/5.0.0 branch name can supply the same external baseline.

The distance remains available when a deployment mode incorporates the count into the pre-release number and clears BuildMetaData. On a selected tag at HEAD, both source SHAs are HEAD and distance is zero. Sha and ShortSha always identify the current commit.

See calculation strategies for selection and counting rules. Missing source values are JSON null in the new fields; textual outputs such as environment variables and MSBuild properties use empty strings.

Formatting Variables

GitVersion variables can be formatted using C# format strings. See Format Strings for details.