Skip to content

VersionSourceDistance as a replacement for the existing CommitsSinceVersionSource #4810

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
arturcic merged 18 commits into from
Feb 1, 2026
Merged

VersionSourceDistance as a replacement for the existing CommitsSinceVersionSource #4810

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
18 commits
Select commit Hold shift + click to select a range
bd90636
Add VersionSourceDistance and deprecate CommitsSinceVersionSource
Copilot Jan 31, 2026
0f7458e
Fix VersionSourceDistance property ordering in JSON model
Copilot Jan 31, 2026
4aa2a7b
Fix VB and F# approved test file syntax
Copilot Jan 31, 2026
c4d0bca
Fix test failures: disable CI build for test projects and correct pro…
Copilot Jan 31, 2026
87096f4
Add VersionSourceDistance property to build script GitVersion model
Copilot Feb 1, 2026
fe3617c
Add VersionSourceDistance usage alongside CommitsSinceVersionSource i…
Copilot Feb 1, 2026
486669e
Move VersionSourceDistance API additions from PublicAPI.Shipped.txt t…
Copilot Feb 1, 2026
001061e
build(tests): Remove CI build override
arturcic Jan 31, 2026
f0c381d
test(core): Add test for VersionSourceDistance property
arturcic Jan 31, 2026
5dd893c
build: Suppress CS0618 obsolete member warnings
arturcic Jan 31, 2026
9d8908b
refactor(serializer): Reorder VersionSourceSha property
arturcic Feb 1, 2026
0321038
Feat: Introduce VersionSourceDistance and deprecate CommitsSinceVersi…
arturcic Feb 1, 2026
b26f709
Refactor: Update GitVersionExecutorTests cache file content
arturcic Feb 1, 2026
13448f2
Test: Update core tests for VersionSourceDistance
arturcic Feb 1, 2026
a854f14
Test: Update approved test snapshots for VersionSourceDistance
arturcic Feb 1, 2026
5fec4dd
Build: Expose VersionSourceDistance in MSBuild targets
arturcic Feb 1, 2026
1358781
Docs: Update documentation for VersionSourceDistance
arturcic Feb 1, 2026
849db8a
fix: sonarcloud issues
arturcic Feb 1, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions build/common/Addins/GitVersion/GitVersion.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -95,6 +95,11 @@ public sealed class GitVersion
/// </summary>
public int? CommitsSinceVersionSource { get; set; }

/// <summary>
/// Gets or sets the version source distance.
/// </summary>
public int? VersionSourceDistance { get; set; }

/// <summary>
/// Gets or sets the commit date.
/// </summary>
Expand Down
2 changes: 1 addition & 1 deletion docs/input/docs/reference/configuration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -907,7 +907,7 @@ When `release-2.0.0` is merged into main, we want main to build `2.0.0`. If
prevents incrementing after a versioned branch is merged.

In a GitFlow-based repository, setting this option can have implications on the
`CommitsSinceVersionSource` output variable. It can rule out a potentially
`VersionSourceDistance` output variable. It can rule out a potentially
better version source proposed by the `MergeMessageBaseVersionStrategy`. For
more details and an in-depth analysis, please see [the discussion][2506].

Expand Down
22 changes: 11 additions & 11 deletions docs/input/docs/reference/custom-formatting.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,7 @@ assembly-informational-format: "{Major}.{Minor}.{Patch:F2}-{PreReleaseLabel}"
- `F` or `f` (Fixed-point): `{Patch:F2}` → `"1.23"`
- `N` or `n` (Number): `{BuildMetadata:N0}` → `"1,234"`
- `C` or `c` (Currency): `{Major:C}` → `"¤1.00"`
- `P` or `p` (Percent): `{CommitsSinceVersionSource:P}` → `"12,345.60 %"`
- `P` or `p` (Percent): `{VersionSourceDistance:P}` → `"12,345.60 %"`
- `D` or `d` (Decimal): `{Major:D4}` → `"0001"`
- `B` or `b` (Binary): `{Minor:B4}` → `"0101"`
- `X` or `x` (Hexadecimal): `{Patch:X}` → `"FF"`
Expand Down Expand Up @@ -72,14 +72,14 @@ branches:
feature:
label: "{BranchName:c}" # Converts to PascalCase

assembly-informational-format: "{Major}.{Minor}.{Patch}-{PreReleaseLabel:l}.{CommitsSinceVersionSource:0000}"
assembly-informational-format: "{Major}.{Minor}.{Patch}-{PreReleaseLabel:l}.{VersionSourceDistance:0000}"
```

**Template Usage:**

```yaml
# Using format strings in templates
assembly-informational-format: "{Major}.{Minor}.{Patch}-{CommitsSinceVersionSource:0000}"
assembly-informational-format: "{Major}.{Minor}.{Patch}-{VersionSourceDistance:0000}"
assembly-informational-format: "{SemVer}-{BranchName:l}"
```

Expand All @@ -91,7 +91,7 @@ Based on actual test cases from the implementation:

```yaml
# Zero-padded commit count
assembly-informational-format: "{Major}.{Minor}.{Patch}-{CommitsSinceVersionSource:0000}"
assembly-informational-format: "{Major}.{Minor}.{Patch}-{VersionSourceDistance:0000}"
# Result: "1.2.3-0042"
```

Expand Down Expand Up @@ -122,7 +122,7 @@ assembly-informational-format: "Cost-{Major:C}" # Result: "Cost-¤1.00"
assembly-informational-format: "Progress-{Minor:P}" # Result: "Progress-200.00 %"

# Thousands separator
assembly-informational-format: "Build-{CommitsSinceVersionSource:N0}" # Result: "Build-1,234"
assembly-informational-format: "Build-{VersionSourceDistance:N0}" # Result: "Build-1,234"
```

## Configuration Integration
Expand All @@ -133,9 +133,9 @@ The format strings are used in GitVersion configuration files through various fo

```yaml
# GitVersion.yml
assembly-informational-format: "{Major}.{Minor}.{Patch}-{CommitsSinceVersionSource:0000}"
assembly-informational-format: "{Major}.{Minor}.{Patch}-{VersionSourceDistance:0000}"
assembly-versioning-format: "{Major}.{Minor}.{Patch}.{env:BUILD_NUMBER}"
assembly-file-versioning-format: "{MajorMinorPatch}.{CommitsSinceVersionSource}"
assembly-file-versioning-format: "{MajorMinorPatch}.{VersionSourceDistance}"
```

### Environment Variable Integration
Expand All @@ -152,15 +152,15 @@ Based on the actual test implementation:

```yaml
# Example from VariableProviderTests.cs
assembly-informational-format: "{Major}.{Minor}.{Patch}-{CommitsSinceVersionSource:0000}"
# Result: "1.2.3-0042" when CommitsSinceVersionSource = 42
assembly-informational-format: "{Major}.{Minor}.{Patch}-{VersionSourceDistance:0000}"
# Result: "1.2.3-0042" when VersionSourceDistance = 42

# Branch-specific formatting
branches:
feature:
label: "{BranchName:c}" # PascalCase conversion
hotfix:
label: "hotfix.{CommitsSinceVersionSource:00}"
label: "hotfix.{VersionSourceDistance:00}"
```

## Invariant Culture Formatting
Expand All @@ -174,7 +174,7 @@ The formatting system uses `CultureInfo.InvariantCulture` by default through the

```csharp
// All environments produce the same output:
// {CommitsSinceVersionSource:N0} → "1,234"
// {VersionSourceDistance:N0} → "1,234"
// {CommitDate:MMM dd, yyyy} → "Mar 15, 2024"
// {Major:C} → "¤1.00" (generic currency symbol)
```
Expand Down
2 changes: 1 addition & 1 deletion docs/input/docs/reference/mdsource/configuration.source.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -508,7 +508,7 @@ When `release-2.0.0` is merged into main, we want main to build `2.0.0`. If
prevents incrementing after a versioned branch is merged.

In a GitFlow-based repository, setting this option can have implications on the
`CommitsSinceVersionSource` output variable. It can rule out a potentially
`VersionSourceDistance` output variable. It can rule out a potentially
better version source proposed by the `MergeMessageBaseVersionStrategy`. For
more details and an in-depth analysis, please see [the discussion][2506].

Expand Down
56 changes: 29 additions & 27 deletions docs/input/docs/reference/variables.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,40 +34,42 @@ what is available. For the `release/3.0.0` branch of GitVersion it shows:
"ShortSha": "28c8531",
"VersionSourceSha": "28c853159a46b5a87e6cc9c4f6e940c59d6bc68a",
"CommitsSinceVersionSource": 7,
"VersionSourceDistance": 7,
"CommitDate": "2021-12-31",
"UncommittedChanges": 0
}
```

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

| Property | Description |
| --------------------------------: | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Major` | The major version. Should be incremented on breaking changes. |
| `Minor` | The minor version. Should be incremented on new features. |
| `Patch` | The patch version. Should be incremented on bug fixes. |
| `PreReleaseTag` | The pre-release tag is the pre-release label suffixed by the `PreReleaseNumber`. |
| `PreReleaseTagWithDash` | The pre-release tag prefixed with a dash. |
| `PreReleaseLabel` | The pre-release label. |
| `PreReleaseLabelWithDash` | The pre-release label prefixed with a dash. |
| `PreReleaseNumber` | The pre-release number. |
| `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. |
| `BuildMetaData` | The build metadata, usually representing number of commits since the `VersionSourceSha`. Despite its name, will not increment for every build. |
| `FullBuildMetaData` | The `BuildMetaData` suffixed with `BranchName` and `Sha`. |
| `MajorMinorPatch` | `Major`, `Minor` and `Patch` joined together, separated by `.`. |
| `SemVer` | The semantical version number, including `PreReleaseTagWithDash` for pre-release version numbers. |
| `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. |
| `AssemblySemFileVer` | Suitable for .NET `AssemblyFileVersion`. Defaults to `Major.Minor.Patch.0`. |
| `InformationalVersion` | Suitable for .NET `AssemblyInformationalVersion`. Defaults to `FullSemVer` suffixed by `FullBuildMetaData`. |
| `FullSemVer` | The full, SemVer 2.0 compliant version number. |
| `BranchName` | The name of the checked out Git branch. |
| `EscapedBranchName` | Equal to `BranchName`, but with `/` replaced with `-`. |
| `Sha` | The SHA of the Git commit. |
| `ShortSha` | The `Sha` limited to 7 characters. |
| `VersionSourceSha` | The SHA of the commit used as version source. |
| `CommitsSinceVersionSource` | The number of commits since the version source. |
| `CommitDate` | The ISO-8601 formatted date of the commit identified by `Sha`. |
| `UncommittedChanges` | The number of uncommitted changes present in the repository. |
| Property | Description |
|----------------------------:|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `Major` | The major version. Should be incremented on breaking changes. |
| `Minor` | The minor version. Should be incremented on new features. |
| `Patch` | The patch version. Should be incremented on bug fixes. |
| `PreReleaseTag` | The pre-release tag is the pre-release label suffixed by the `PreReleaseNumber`. |
| `PreReleaseTagWithDash` | The pre-release tag prefixed with a dash. |
| `PreReleaseLabel` | The pre-release label. |
| `PreReleaseLabelWithDash` | The pre-release label prefixed with a dash. |
| `PreReleaseNumber` | The pre-release number. |
| `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. |
| `BuildMetaData` | The build metadata, usually representing number of commits since the `VersionSourceSha`. Despite its name, will not increment for every build. |
| `FullBuildMetaData` | The `BuildMetaData` suffixed with `BranchName` and `Sha`. |
| `MajorMinorPatch` | `Major`, `Minor` and `Patch` joined together, separated by `.`. |
| `SemVer` | The semantical version number, including `PreReleaseTagWithDash` for pre-release version numbers. |
| `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. |
| `AssemblySemFileVer` | Suitable for .NET `AssemblyFileVersion`. Defaults to `Major.Minor.Patch.0`. |
| `InformationalVersion` | Suitable for .NET `AssemblyInformationalVersion`. Defaults to `FullSemVer` suffixed by `FullBuildMetaData`. |
| `FullSemVer` | The full, SemVer 2.0 compliant version number. |
| `BranchName` | The name of the checked out Git branch. |
| `EscapedBranchName` | Equal to `BranchName`, but with `/` replaced with `-`. |
| `Sha` | The SHA of the Git commit. |
| `ShortSha` | The `Sha` limited to 7 characters. |
| `VersionSourceSha` | The SHA of the commit used as version source. |
| `CommitsSinceVersionSource` | (Deprecated: use `VersionSourceDistance` instead) The number of commits since the version source. |
| `VersionSourceDistance` | The number of commits since the version source. |
| `CommitDate` | The ISO-8601 formatted date of the commit identified by `Sha`. |
| `UncommittedChanges` | The number of uncommitted changes present in the repository. |

Depending on how and in which context GitVersion is executed (for instance
within a [supported build server][build-servers]), the above version variables
Expand Down
2 changes: 1 addition & 1 deletion src/Directory.Build.props
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@
<RepositoryType>git</RepositoryType>

<NoWarn>$(NoWarn);NU1701;1591,8618,SYSLIB10;EnableGenerateDocumentationFile</NoWarn>
<NoWarn>$(NoWarn);CS8604;CS8620</NoWarn>
<NoWarn>$(NoWarn);CS8604;CS8620;CS0618</NoWarn>
<WarningsAsErrors>$(WarningsAsErrors);RS0016;RS0017;RS0022;RS0024;RS0025;RS0026;RS0027</WarningsAsErrors>

<DebugType>embedded</DebugType>
Expand Down
Loading
Loading