GitTools · arturcic · Sep 9, 2026
diff --git a/docs/diagrams/version-calculation.mmd b/docs/diagrams/version-calculation.mmd
@@ -6,7 +6,8 @@ sequenceDiagram
 
     Next->>Base: GetBaseVersion
     Note right of Base: Determine the base version
-    Base-->>Next: 2.0.0 at 25e4ba
+    Base-->>Next: Semantic baseline 2.0.0 and its provenance
+    Next->>Next: Select counting anchor independently
 
     alt Base version allows increment
         Config->>Next: Branch increment strategy (patch)
@@ -23,7 +24,7 @@ sequenceDiagram
         Note right of Next: 2.0.1-alpha.1
     end
 
-    Next->>Metadata: Context
-    Metadata-->>Next: Commit count and branch/SHA metadata
+    Next->>Metadata: Semantic provenance and counting anchor
+    Metadata-->>Next: Count from anchor, both sources, and current branch/SHA metadata
     Next->>Next: Apply commit count and metadata
     Note right of Next: 2.0.1-alpha.1+10
diff --git a/docs/input/docs/migration/v6-to-v7.md b/docs/input/docs/migration/v6-to-v7.md
@@ -44,6 +44,16 @@ macOS.
 
 Use `VersionSourceDistance` instead; it has the same value.
 
+## Separate semantic and counting sources
+
+Five additive output variables distinguish semantic provenance from counting: `SemVerSourceSemVer`, `SemVerSourceSha`, `SemVerSourceIncrement`, `CommitCountSourceSha`, and `CommitCountSourceDistance`. They are available in JSON, custom formats, generated version-information files, build-server output, and MSBuild.
+
+Existing `VersionSource*` fields keep their values. `VersionSourceSha` identifies the counting anchor, which may not be the artifact supplying `VersionSourceSemVer`. The legacy `VersionSourceIncrement` can be `None` after candidate resolution even when an increment was applied; new integrations should use `SemVerSourceIncrement`.
+
+For the removed v6 `CommitsSinceVersionSource`, `VersionSourceDistance` remains a compatible replacement; `CommitCountSourceDistance` is the explicit name for the same count. Do not replace that count with a distance from `SemVerSourceSha`: configuration and branch-name sources have no intrinsic SHA. New nullable source fields use JSON null; textual outputs use an empty string.
+
+Update strict JSON property-set consumers for the five added fields. Public source interfaces and existing constructors remain available. This change does not alter candidate ordering, version numbers, or commit counts. See [version variables](/docs/reference/variables) for a concrete example.
+
 ## CLI Arguments - POSIX-style syntax
 
 GitVersion now uses POSIX-style command-line arguments powered by System.CommandLine.

diff --git a/docs/input/docs/reference/custom-formatting.md b/docs/input/docs/reference/custom-formatting.md
@@ -51,6 +51,18 @@ output:
   custom-version-format: '{env:ANDROID_VERSION_CODE}'
 ```
 
+## Source variables
+
+Use `CommitCountSourceDistance` when formatting the count, and `SemVerSourceSemVer` or `SemVerSourceIncrement` when describing the selected semantic baseline:
+
+```yaml
+output:
+  assembly-informational-format: '{SemVerSourceSemVer}-{SemVerSourceIncrement}+{CommitCountSourceDistance:000}'
+  # Example: 5.0.0-None+002 for an external 5.0.0 baseline and two counted commits.
+```
+
+`SemVerSourceSha` can be absent for configuration or branch-name sources; it is not a substitute for `Sha` (HEAD) or `CommitCountSourceSha` (the counting anchor). Existing `VersionSource*` format names remain available for compatibility.
+
 ## Overview
 
 The custom formatter functionality introduces several new formatters that can be used in GitVersion configuration files and templates:

diff --git a/docs/input/docs/reference/variables.md b/docs/input/docs/reference/variables.md
@@ -16,6 +16,8 @@ the repository history and effective configuration:
     "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",
@@ -32,13 +34,16 @@ the repository history and effective configuration:
     "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": "28c853159a46b5a87e6cc9c4f6e940c59d6bc68a",
+    "VersionSourceSha": "previous-source-commit-sha",
     "WeightedPreReleaseNumber": 1099
 }
 ```
@@ -50,7 +55,9 @@ Each property of the above JSON document is described in the below table.
 |        `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 `VersionSourceSha`. Despite its name, will not increment for every build.                             |
+|             `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 `-`.                                                                                                                     |
@@ -67,20 +74,31 @@ Each property of the above JSON document is described in the below table.
 |           `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` | The number of commits since the version source.                                                                                                                            |
-|    `VersionSourceIncrement` | The increment strategy used for the version calculation. Possible values: `None`, `Patch`, `Minor`, `Major`.                                                               |
-|       `VersionSourceSemVer` | The semantic version of the commit used as version source.                                                                                                                 |
-|          `VersionSourceSha` | The SHA of the commit used as version source.                                                                                                                              |
+|     `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][build-servers]), 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](/docs/reference/version-sources) 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](/docs/reference/custom-formatting) for details.

diff --git a/docs/input/docs/reference/version-sources.md b/docs/input/docs/reference/version-sources.md
@@ -20,12 +20,24 @@ Strategies are selected with the [`strategies` configuration setting](/docs/refe
 
 ## Selection and increments
 
-The order of entries in `strategies` is not a priority list. GitVersion evaluates candidates and selects a next version with a corresponding version source. Fallback is deferred until other strategies have been considered.
+The order of entries in `strategies` is not a priority list. GitVersion evaluates candidates and selects a next version, preserving its semantic source separately from the commit-count anchor. Fallback is deferred until other strategies have been considered.
 
 Do not interpret a source as “always increments” or “never increments” without the relevant branch configuration. Tagged commits, merge handling, increment inheritance, and deployment mode affect the outcome.
 
 For the sequence of operations, see [how versions are calculated](/docs/learn/how-it-works).
 
+## Semantic source and commit-count source
+
+The **semantic source** supplies the baseline version and its final increment. Tags and merge messages have associated commits. Configuration values and branch names are external sources: they do not intrinsically belong to a commit. Mainline can fold several operations into a derived baseline while retaining its source provenance. The source is not a detector for every commit that contains a version-bump message.
+
+The **commit-count source** anchors the count of commits reachable from the current commit, excluding commits reachable from the anchor and applying the configured ignore filters. This is a graph count, not first-parent distance or a count of builds. A null anchor counts all reachable, non-ignored history.
+
+GitVersion compares candidates by their incremented semantic version. For multiple equal candidates with source commits, it selects the latest source timestamp. Otherwise the counting search prefers a commit-backed candidate by descending incremented version and then source timestamp. When the winning version is stable, pre-release base candidates are excluded from this counting search. Only when no commit-backed candidate remains does it use a null anchor. The order in `strategies` does not establish precedence.
+
+For example, a `1.0.0` tag can remain the counting anchor while configuration or the branch name `release/5.0.0` supplies a `5.0.0` baseline. Replacing that anchor with the external semantic source would reset the meaning of the count. A later tag that raises the numeric version is reflected in semantic provenance without changing the selected counting anchor.
+
+See the `SemVerSource*` and `CommitCountSource*` [output variables](/docs/reference/variables). The legacy `VersionSource*` fields retain their existing values for compatibility; they mix the two concepts.
+
 ## Existing source topics
 
 The following anchors are retained for older links.

diff --git a/schemas/7.0/GitVersion.json b/schemas/7.0/GitVersion.json
@@ -27,12 +27,26 @@
       ]
     },
     "BuildMetaData": {
-      "description": "The build metadata, usually representing number of commits since the VersionSourceSha.",
+      "description": "The build metadata, usually representing number of commits since the CommitCountSourceSha.",
       "type": [
         "null",
         "integer"
       ]
     },
+    "CommitCountSourceDistance": {
+      "description": "The number of non-ignored commits reachable from HEAD but not from the counting anchor.",
+      "type": [
+        "null",
+        "integer"
+      ]
+    },
+    "CommitCountSourceSha": {
+      "description": "The commit used as the counting anchor, or null when counting all reachable history.",
+      "type": [
+        "null",
+        "string"
+      ]
+    },
     "CommitDate": {
       "description": "The ISO-8601 formatted date of the commit identified by Sha.",
       "type": [
@@ -145,6 +159,27 @@
         "string"
       ]
     },
+    "SemVerSourceIncrement": {
+      "description": "The final increment relative to the semantic baseline: None, Patch, Minor or Major.",
+      "type": [
+        "null",
+        "string"
+      ]
+    },
+    "SemVerSourceSemVer": {
+      "description": "The semantic baseline supplied by the selected artifact or derivation.",
+      "type": [
+        "null",
+        "string"
+      ]
+    },
+    "SemVerSourceSha": {
+      "description": "The semantic source commit SHA, or null for external sources such as configuration or a branch name.",
+      "type": [
+        "null",
+        "string"
+      ]
+    },
     "Sha": {
       "description": "The SHA of the Git commit.",
       "type": [
@@ -167,7 +202,7 @@
       ]
     },
     "VersionSourceDistance": {
-      "description": "The number of commits since the version source.",
+      "description": "Compatibility alias for CommitCountSourceDistance.",
       "type": [
         "null",
         "integer"
@@ -181,14 +216,14 @@
       ]
     },
     "VersionSourceSemVer": {
-      "description": "The semantic version of the commit used as version source.",
+      "description": "Legacy semantic baseline; it need not come from VersionSourceSha. Prefer SemVerSourceSemVer.",
       "type": [
         "null",
         "string"
       ]
     },
     "VersionSourceSha": {
-      "description": "The SHA of the commit used as version source.",
+      "description": "Compatibility alias for CommitCountSourceSha.",
       "type": [
         "null",
         "string"

diff --git a/...tVersion.Core.Tests/VersionCalculation/Approved/JsonVersionBuilderTests.Json.approved.txt b/...tVersion.Core.Tests/VersionCalculation/Approved/JsonVersionBuilderTests.Json.approved.txt
@@ -3,6 +3,8 @@
   "AssemblySemVer": "1.2.0.0",
   "BranchName": "feature1",
   "BuildMetaData": 5,
+  "CommitCountSourceDistance": 5,
+  "CommitCountSourceSha": "versionSourceSha",
   "CommitDate": "2014-03-06",
   "CustomVersion": "",
   "EscapedBranchName": "feature1",
@@ -19,6 +21,9 @@
   "PreReleaseLabel": "unstable.4",
   "PreReleaseLabelWithDash": "-unstable.4",
   "SemVer": "1.2.0-unstable.4",
+  "SemVerSourceIncrement": "None",
+  "SemVerSourceSemVer": null,
+  "SemVerSourceSha": null,
   "Sha": "commitSha",
   "ShortSha": "commitShortSha",
   "UncommittedChanges": 0,

diff --git a/...iableProviderTests.ProvidesVariablesInContinuousDeliveryModeForFeatureBranch.approved.txt b/...iableProviderTests.ProvidesVariablesInContinuousDeliveryModeForFeatureBranch.approved.txt
@@ -3,6 +3,8 @@
   "AssemblySemVer": "1.2.3.0",
   "BranchName": "feature/123",
   "BuildMetaData": 5,
+  "CommitCountSourceDistance": 5,
+  "CommitCountSourceSha": "versionSourceSha",
   "CommitDate": "2014-03-06",
   "CustomVersion": "",
   "EscapedBranchName": "feature-123",
@@ -19,6 +21,9 @@
   "PreReleaseLabel": "",
   "PreReleaseLabelWithDash": "",
   "SemVer": "1.2.3",
+  "SemVerSourceIncrement": "None",
+  "SemVerSourceSemVer": null,
+  "SemVerSourceSha": null,
   "Sha": "commitSha",
   "ShortSha": "commitShortSha",
   "UncommittedChanges": 0,

diff --git a/...ariablesInContinuousDeliveryModeForFeatureBranchWithCustomAssemblyInfoFormat.approved.txt b/...ariablesInContinuousDeliveryModeForFeatureBranchWithCustomAssemblyInfoFormat.approved.txt
@@ -3,6 +3,8 @@
   "AssemblySemVer": "1.2.3.0",
   "BranchName": "feature/123",
   "BuildMetaData": 5,
+  "CommitCountSourceDistance": 5,
+  "CommitCountSourceSha": "versionSourceSha",
   "CommitDate": "2014-03-06",
   "CustomVersion": "",
   "EscapedBranchName": "feature-123",
@@ -19,6 +21,9 @@
   "PreReleaseLabel": "",
   "PreReleaseLabelWithDash": "",
   "SemVer": "1.2.3",
+  "SemVerSourceIncrement": "None",
+  "SemVerSourceSemVer": null,
+  "SemVerSourceSha": null,
   "Sha": "commitSha",
   "ShortSha": "commitShortSha",
   "UncommittedChanges": 0,

diff --git a/...VariableProviderTests.ProvidesVariablesInContinuousDeliveryModeForPreRelease.approved.txt b/...VariableProviderTests.ProvidesVariablesInContinuousDeliveryModeForPreRelease.approved.txt
@@ -3,6 +3,8 @@
   "AssemblySemVer": "1.2.3.0",
   "BranchName": "develop",
   "BuildMetaData": 5,
+  "CommitCountSourceDistance": 5,
+  "CommitCountSourceSha": "versionSourceSha",
   "CommitDate": "2014-03-06",
   "CustomVersion": "",
   "EscapedBranchName": "develop",
@@ -19,6 +21,9 @@
   "PreReleaseLabel": "unstable.4",
   "PreReleaseLabelWithDash": "-unstable.4",
   "SemVer": "1.2.3-unstable.4",
+  "SemVerSourceIncrement": "None",
+  "SemVerSourceSemVer": null,
+  "SemVerSourceSha": null,
   "Sha": "commitSha",
   "ShortSha": "commitShortSha",
   "UncommittedChanges": 0,

diff --git a/...ved/VariableProviderTests.ProvidesVariablesInContinuousDeliveryModeForStable.approved.txt b/...ved/VariableProviderTests.ProvidesVariablesInContinuousDeliveryModeForStable.approved.txt
@@ -3,6 +3,8 @@
   "AssemblySemVer": "1.2.3.0",
   "BranchName": "develop",
   "BuildMetaData": 5,
+  "CommitCountSourceDistance": 5,
+  "CommitCountSourceSha": "versionSourceSha",
   "CommitDate": "2014-03-06",
   "CustomVersion": "",
   "EscapedBranchName": "develop",
@@ -19,6 +21,9 @@
   "PreReleaseLabel": "",
   "PreReleaseLabelWithDash": "",
   "SemVer": "1.2.3",
+  "SemVerSourceIncrement": "None",
+  "SemVerSourceSemVer": null,
+  "SemVerSourceSha": null,
   "Sha": "commitSha",
   "ShortSha": "commitShortSha",
   "UncommittedChanges": 0,

diff --git a/...Tests.ProvidesVariablesInContinuousDeploymentModeForMainBranchWithEmptyLabel.approved.txt b/...Tests.ProvidesVariablesInContinuousDeploymentModeForMainBranchWithEmptyLabel.approved.txt
@@ -3,6 +3,8 @@
   "AssemblySemVer": "1.2.3.0",
   "BranchName": "main",
   "BuildMetaData": null,
+  "CommitCountSourceDistance": 5,
+  "CommitCountSourceSha": "versionSourceSha",
   "CommitDate": "2014-03-06",
   "CustomVersion": "",
   "EscapedBranchName": "main",
@@ -19,6 +21,9 @@
   "PreReleaseLabel": "9",
   "PreReleaseLabelWithDash": "-9",
   "SemVer": "1.2.3-9",
+  "SemVerSourceIncrement": "None",
+  "SemVerSourceSemVer": null,
+  "SemVerSourceSha": null,
   "Sha": "commitSha",
   "ShortSha": "commitShortSha",
   "UncommittedChanges": 0,