GitTools · arturcic · Jul 24, 2026 · Jul 24, 2026 · Jul 24, 2026
diff --git a/docs/input/docs/reference/configuration.md b/docs/input/docs/reference/configuration.md
@@ -519,6 +519,13 @@ Specifies the format of `AssemblyInformationalVersion`.
 Follows the same formatting semantics as `assembly-file-versioning-format`.
 The default value is `{InformationalVersion}`.
 
+### custom-version-format
+
+Specifies the format of the `CustomVersion` output variable.
+Follows the same formatting semantics as `assembly-file-versioning-format` and
+can use version variables or environment variables. The default value is
+`{SemVer}`.
+
 ### mode
 
 Sets the `mode` of how GitVersion should create a new version. Read more at

diff --git a/docs/input/docs/reference/custom-formatting.md b/docs/input/docs/reference/custom-formatting.md
@@ -5,6 +5,37 @@ description: Using C# format strings in GitVersion configuration
 
 GitVersion supports C# format strings in configuration, allowing you to apply standard .NET formatting and custom transformations to version properties. This enhancement provides more flexibility and control over how version information is displayed and used throughout your build process.
 
+## Custom Version Output
+
+Set `custom-version-format` to add a `CustomVersion` value to GitVersion's
+output without changing the meaning of any existing version variable. It uses
+the same version and environment variable formatting described below and
+defaults to `{SemVer}`.
+
+For example, a PEP 440-compatible pre-release version can omit SemVer's dash and
+separator:
+
+```yaml
+custom-version-format: '{Major}.{Minor}.{Patch}{PreReleaseLabel:l}{PreReleaseNumber}'
+# 0.6.3-beta.10 becomes CustomVersion 0.6.3beta10
+```
+
+A fixed-width numeric format can provide an increasing integer version for
+platforms such as Android:
+
+```yaml
+custom-version-format: '{Major:00}{Minor:00}{Patch:000}'
+# 0.0.123 becomes 0000123; 0.1.0 becomes 0001000
+```
+
+Choose widths that are large enough for each version component and keep the
+result within the target platform's integer limit. If the CI system owns the
+monotonically increasing build number, it can be exposed directly instead:
+
+```yaml
+custom-version-format: '{env:ANDROID_VERSION_CODE}'
+```
+
 ## 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/mdsource/configuration.source.md b/docs/input/docs/reference/mdsource/configuration.source.md
@@ -120,6 +120,13 @@ Specifies the format of `AssemblyInformationalVersion`.
 Follows the same formatting semantics as `assembly-file-versioning-format`.
 The default value is `{InformationalVersion}`.
 
+### custom-version-format
+
+Specifies the format of the `CustomVersion` output variable.
+Follows the same formatting semantics as `assembly-file-versioning-format` and
+can use version variables or environment variables. The default value is
+`{SemVer}`.
+
 ### mode
 
 Sets the `mode` of how GitVersion should create a new version. Read more at

diff --git a/docs/input/docs/reference/variables.md b/docs/input/docs/reference/variables.md
@@ -16,6 +16,7 @@ what is available. For the `release/3.0.0` branch of GitVersion it shows:
     "BranchName": "release/3.022.011",
     "BuildMetaData": 88,
     "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",
@@ -50,6 +51,7 @@ Each property of the above JSON document is described in the below table.
 |                `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.                             |
 |                `CommitDate` | The ISO-8601 formatted date of the commit identified by `Sha`.                                                                                                             |
+|             `CustomVersion` | A custom version configured with `custom-version-format`. Defaults to `SemVer`.                                                                                            |
 |         `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.                                                                                                                             |

diff --git a/docs/input/docs/usage/cli/arguments.md b/docs/input/docs/usage/cli/arguments.md
@@ -127,17 +127,18 @@ Following options are supported:
 5. `assembly-versioning-scheme`
 6. `commit-date-format`
 7. `commit-message-incrementing`
-8. `label`
-9. `increment`
-10. `major-version-bump-message`
-11. `minor-version-bump-message`
-12. `mode`
-13. `next-version`
-14. `no-bump-message`
-15. `patch-version-bump-message`
-16. `tag-prefix`
-17. `tag-pre-release-weight`
-18. `update-build-number`
+8. `custom-version-format`
+9. `label`
+10. `increment`
+11. `major-version-bump-message`
+12. `minor-version-bump-message`
+13. `mode`
+14. `next-version`
+15. `no-bump-message`
+16. `patch-version-bump-message`
+17. `tag-prefix`
+18. `tag-pre-release-weight`
+19. `update-build-number`
 
 Read more about [Configuration](/docs/reference/configuration).
 

diff --git a/schemas/7.0/GitVersion.configuration.json b/schemas/7.0/GitVersion.configuration.json
@@ -168,6 +168,14 @@
         null
       ]
     },
+    "custom-version-format": {
+      "description": "Specifies the format of CustomVersion. Defaults to '{SemVer}'.",
+      "default": "'{SemVer}'",
+      "type": [
+        "null",
+        "string"
+      ]
+    },
     "mode": {
       "description": "The deployment mode for this branch. Can be 'ManualDeployment', 'ContinuousDelivery', 'ContinuousDeployment'.",
       "enum": [

diff --git a/schemas/7.0/GitVersion.json b/schemas/7.0/GitVersion.json
@@ -40,6 +40,13 @@
         "string"
       ]
     },
+    "CustomVersion": {
+      "description": "A custom version computed from custom-version-format. Defaults to SemVer.",
+      "type": [
+        "null",
+        "string"
+      ]
+    },
     "EscapedBranchName": {
       "description": "Equal to BranchName, but with / replaced with -.",
       "type": [

diff --git a/src/GitVersion.App.Tests/ArgumentParserTests.cs b/src/GitVersion.App.Tests/ArgumentParserTests.cs
@@ -449,6 +449,13 @@ private static IEnumerable<TestCaseData> OverrideConfigWithSingleOptionTestData(
                 AssemblyFileVersioningFormat = "{Major}.{Minor}.{Patch}.{env:CI_JOB_ID ?? 0}"
             }
         );
+        yield return new TestCaseData(
+            "custom-version-format=\"{Major}.{Minor}.{Patch}{PreReleaseLabel:l}{PreReleaseNumber}\"",
+            new GitVersionConfiguration
+            {
+                CustomVersionFormat = "{Major}.{Minor}.{Patch}{PreReleaseLabel:l}{PreReleaseNumber}"
+            }
+        );
         yield return new TestCaseData(
             "mode=ContinuousDelivery",
             new GitVersionConfiguration

diff --git a/src/GitVersion.App.Tests/LegacyArgumentParserTests.cs b/src/GitVersion.App.Tests/LegacyArgumentParserTests.cs
@@ -439,6 +439,13 @@ private static IEnumerable<TestCaseData> OverrideConfigWithSingleOptionTestData(
                 AssemblyFileVersioningFormat = "{Major}.{Minor}.{Patch}.{env:CI_JOB_ID ?? 0}"
             }
         );
+        yield return new TestCaseData(
+            "custom-version-format=\"{Major}.{Minor}.{Patch}{PreReleaseLabel:l}{PreReleaseNumber}\"",
+            new GitVersionConfiguration
+            {
+                CustomVersionFormat = "{Major}.{Minor}.{Patch}{PreReleaseLabel:l}{PreReleaseNumber}"
+            }
+        );
         yield return new TestCaseData(
             "mode=ContinuousDelivery",
             new GitVersionConfiguration

diff --git a/src/GitVersion.Configuration.Tests/Configuration/ConfigurationProviderTests.cs b/src/GitVersion.Configuration.Tests/Configuration/ConfigurationProviderTests.cs
@@ -242,6 +242,32 @@ public void CanUpdateAssemblyInformationalVersioningSchemeWithFullSemVer()
         configuration.AssemblyInformationalFormat.ShouldBe("{FullSemVer}");
     }
 
+    [Test]
+    public void CanReadCustomVersionFormat()
+    {
+        const string text = "custom-version-format: '{Major}.{Minor}.{Patch}{PreReleaseLabel:l}{PreReleaseNumber}'";
+        using var _ = this.fileSystem.SetupConfigFile(path: this.repoPath, text: text);
+
+        var configuration = this.configurationProvider.ProvideForDirectory(this.repoPath);
+
+        configuration.CustomVersionFormat.ShouldBe("{Major}.{Minor}.{Patch}{PreReleaseLabel:l}{PreReleaseNumber}");
+    }
+
+    [Test]
+    public void CanOverrideCustomVersionFormat()
+    {
+        const string text = "custom-version-format: '{SemVer}'";
+        using var _ = this.fileSystem.SetupConfigFile(path: this.repoPath, text: text);
+        var overrideConfiguration = new Dictionary<object, object?>
+        {
+            ["custom-version-format"] = "{Major:00}{Minor:00}{Patch:000}"
+        };
+
+        var configuration = this.configurationProvider.ProvideForDirectory(this.repoPath, overrideConfiguration);
+
+        configuration.CustomVersionFormat.ShouldBe("{Major:00}{Minor:00}{Patch:000}");
+    }
+
     [Test]
     public void CanReadDefaultDocument()
     {
@@ -251,6 +277,7 @@ public void CanReadDefaultDocument()
         configuration.AssemblyVersioningScheme.ShouldBe(AssemblyVersioningScheme.MajorMinorPatch);
         configuration.AssemblyFileVersioningScheme.ShouldBe(AssemblyFileVersioningScheme.MajorMinorPatch);
         configuration.AssemblyInformationalFormat.ShouldBe(null);
+        configuration.CustomVersionFormat.ShouldBe(null);
         configuration.Branches["develop"].Label.ShouldBe("alpha");
         configuration.Branches["release"].Label.ShouldBe("beta");
         configuration.TagPrefixPattern.ShouldBe(RegexPatterns.Configuration.DefaultTagPrefixRegexPattern);
@@ -381,6 +408,7 @@ public void ShouldNotOverrideAnythingWhenOverrideConfigIsEmpty()
         configuration.AssemblyInformationalFormat.ShouldBe(expectedConfig.AssemblyInformationalFormat);
         configuration.AssemblyVersioningFormat.ShouldBe(expectedConfig.AssemblyVersioningFormat);
         configuration.AssemblyFileVersioningFormat.ShouldBe(expectedConfig.AssemblyFileVersioningFormat);
+        configuration.CustomVersionFormat.ShouldBe(expectedConfig.CustomVersionFormat);
         configuration.TagPrefixPattern.ShouldBe(expectedConfig.TagPrefixPattern);
         configuration.NextVersion.ShouldBe(expectedConfig.NextVersion);
         configuration.MajorVersionBumpMessage.ShouldBe(expectedConfig.MajorVersionBumpMessage);

diff --git a/src/GitVersion.Configuration/Builders/ConfigurationBuilderBase.cs b/src/GitVersion.Configuration/Builders/ConfigurationBuilderBase.cs
@@ -12,6 +12,7 @@ internal abstract class ConfigurationBuilderBase<TConfigurationBuilder> : IConfi
     private string? assemblyInformationalFormat;
     private string? assemblyVersioningFormat;
     private string? assemblyFileVersioningFormat;
+    private string? customVersionFormat;
     private string? tagPrefix;
     private string? versionInBranchPattern;
     private string? nextVersion;
@@ -129,6 +130,12 @@ public TConfigurationBuilder WithAssemblyFileVersioningFormat(string? value)
         return (TConfigurationBuilder)this;
     }
 
+    public TConfigurationBuilder WithCustomVersionFormat(string? value)
+    {
+        this.customVersionFormat = value;
+        return (TConfigurationBuilder)this;
+    }
+
     public TConfigurationBuilder WithTagPrefixPattern(string? value)
     {
         this.tagPrefix = value;
@@ -329,6 +336,7 @@ public TConfigurationBuilder WithConfiguration(IGitVersionConfiguration value)
         WithAssemblyInformationalFormat(value.AssemblyInformationalFormat);
         WithAssemblyVersioningFormat(value.AssemblyVersioningFormat);
         WithAssemblyFileVersioningFormat(value.AssemblyFileVersioningFormat);
+        WithCustomVersionFormat(value.CustomVersionFormat);
         WithTagPrefixPattern(value.TagPrefixPattern);
         WithVersionInBranchPattern(value.VersionInBranchPattern);
         WithNextVersion(value.NextVersion);
@@ -387,6 +395,7 @@ public virtual IGitVersionConfiguration Build()
             AssemblyInformationalFormat = this.assemblyInformationalFormat,
             AssemblyVersioningFormat = this.assemblyVersioningFormat,
             AssemblyFileVersioningFormat = this.assemblyFileVersioningFormat,
+            CustomVersionFormat = this.customVersionFormat,
             TagPrefixPattern = this.tagPrefix,
             VersionInBranchPattern = this.versionInBranchPattern,
             NextVersion = this.nextVersion,

diff --git a/src/GitVersion.Configuration/GitVersionConfiguration.cs b/src/GitVersion.Configuration/GitVersionConfiguration.cs
@@ -34,6 +34,11 @@ internal sealed record GitVersionConfiguration : BranchConfiguration, IGitVersio
     [JsonPropertyDescription("Specifies the format of AssemblyFileVersion and overwrites the value of assembly-file-versioning-scheme.")]
     public string? AssemblyFileVersioningFormat { get; set; }
 
+    [JsonPropertyName("custom-version-format")]
+    [JsonPropertyDescription($"Specifies the format of CustomVersion. Defaults to '{DefaultCustomVersionFormat}'.")]
+    [JsonPropertyDefault($"'{DefaultCustomVersionFormat}'")]
+    public string? CustomVersionFormat { get; set; }
+
     [JsonPropertyName("tag-prefix")]
     [JsonPropertyDescription($"A regular expression which is used to trim Git tags before processing. Defaults to '{RegexPatterns.Configuration.DefaultTagPrefixRegexPattern}'")]
     [JsonPropertyDefault(RegexPatterns.Configuration.DefaultTagPrefixRegexPattern)]

diff --git a/src/GitVersion.Core.Tests/Core/GitVersionExecutorTests.cs b/src/GitVersion.Core.Tests/Core/GitVersionExecutorTests.cs
@@ -27,6 +27,7 @@ public class GitVersionExecutorTests : TestBase
           "BranchName": "feature/test",
           "BuildMetaData": null,
           "CommitDate": "2015-11-10T00:00:00.000Z",
+          "CustomVersion": "4.10.3-test.19",
           "EscapedBranchName": "feature-test",
           "FullBuildMetaData": "Branch.feature/test.Sha.dd2a29aff0c948e1bdf3dabbe13e1576e70d5f9f",
           "FullSemVer": "4.10.3-test.19",

diff --git a/src/GitVersion.Core.Tests/Helpers/TestableGitVersionVariables.cs b/src/GitVersion.Core.Tests/Helpers/TestableGitVersionVariables.cs
@@ -8,6 +8,7 @@ internal record TestableGitVersionVariables() : GitVersionVariables(
     BranchName: "",
     BuildMetaData: "",
     CommitDate: "",
+    CustomVersion: "",
     EscapedBranchName: "",
     FullBuildMetaData: "",
     FullSemVer: "",

diff --git a/...tVersion.Core.Tests/VersionCalculation/Approved/JsonVersionBuilderTests.Json.approved.txt b/...tVersion.Core.Tests/VersionCalculation/Approved/JsonVersionBuilderTests.Json.approved.txt
@@ -4,6 +4,7 @@
   "BranchName": "feature1",
   "BuildMetaData": 5,
   "CommitDate": "2014-03-06",
+  "CustomVersion": "1.2.0-unstable.4",
   "EscapedBranchName": "feature1",
   "FullBuildMetaData": "5.Branch.feature1.Sha.commitSha",
   "FullSemVer": "1.2.0-unstable.4+5",

diff --git a/...iableProviderTests.ProvidesVariablesInContinuousDeliveryModeForFeatureBranch.approved.txt b/...iableProviderTests.ProvidesVariablesInContinuousDeliveryModeForFeatureBranch.approved.txt
@@ -4,6 +4,7 @@
   "BranchName": "feature/123",
   "BuildMetaData": 5,
   "CommitDate": "2014-03-06",
+  "CustomVersion": "1.2.3",
   "EscapedBranchName": "feature-123",
   "FullBuildMetaData": "5.Branch.feature-123.Sha.commitSha",
   "FullSemVer": "1.2.3+5",

diff --git a/...ariablesInContinuousDeliveryModeForFeatureBranchWithCustomAssemblyInfoFormat.approved.txt b/...ariablesInContinuousDeliveryModeForFeatureBranchWithCustomAssemblyInfoFormat.approved.txt
@@ -4,6 +4,7 @@
   "BranchName": "feature/123",
   "BuildMetaData": 5,
   "CommitDate": "2014-03-06",
+  "CustomVersion": "1.2.3",
   "EscapedBranchName": "feature-123",
   "FullBuildMetaData": "5.Branch.feature-123.Sha.commitSha",
   "FullSemVer": "1.2.3+5",

diff --git a/...VariableProviderTests.ProvidesVariablesInContinuousDeliveryModeForPreRelease.approved.txt b/...VariableProviderTests.ProvidesVariablesInContinuousDeliveryModeForPreRelease.approved.txt
@@ -4,6 +4,7 @@
   "BranchName": "develop",
   "BuildMetaData": 5,
   "CommitDate": "2014-03-06",
+  "CustomVersion": "1.2.3-unstable.4",
   "EscapedBranchName": "develop",
   "FullBuildMetaData": "5.Branch.develop.Sha.commitSha",
   "FullSemVer": "1.2.3-unstable.4+5",

diff --git a/...ved/VariableProviderTests.ProvidesVariablesInContinuousDeliveryModeForStable.approved.txt b/...ved/VariableProviderTests.ProvidesVariablesInContinuousDeliveryModeForStable.approved.txt
@@ -4,6 +4,7 @@
   "BranchName": "develop",
   "BuildMetaData": 5,
   "CommitDate": "2014-03-06",
+  "CustomVersion": "1.2.3",
   "EscapedBranchName": "develop",
   "FullBuildMetaData": "5.Branch.develop.Sha.commitSha",
   "FullSemVer": "1.2.3+5",

diff --git a/...Tests.ProvidesVariablesInContinuousDeploymentModeForMainBranchWithEmptyLabel.approved.txt b/...Tests.ProvidesVariablesInContinuousDeploymentModeForMainBranchWithEmptyLabel.approved.txt
@@ -4,6 +4,7 @@
   "BranchName": "main",
   "BuildMetaData": null,
   "CommitDate": "2014-03-06",
+  "CustomVersion": "1.2.3-9",
   "EscapedBranchName": "main",
   "FullBuildMetaData": "Branch.main.Sha.commitSha",
   "FullSemVer": "1.2.3-9",

diff --git a/...riableProviderTests.ProvidesVariablesInContinuousDeploymentModeForPreRelease.approved.txt b/...riableProviderTests.ProvidesVariablesInContinuousDeploymentModeForPreRelease.approved.txt
@@ -4,6 +4,7 @@
   "BranchName": "develop",
   "BuildMetaData": null,
   "CommitDate": "2014-03-06",
+  "CustomVersion": "1.2.3-unstable.8",
   "EscapedBranchName": "develop",
   "FullBuildMetaData": "Branch.develop.Sha.commitSha",
   "FullSemVer": "1.2.3-unstable.8",

diff --git a/...d/VariableProviderTests.ProvidesVariablesInContinuousDeploymentModeForStable.approved.txt b/...d/VariableProviderTests.ProvidesVariablesInContinuousDeploymentModeForStable.approved.txt
@@ -4,6 +4,7 @@
   "BranchName": "develop",
   "BuildMetaData": null,
   "CommitDate": "2014-03-06",
+  "CustomVersion": "1.2.3-ci.5",
   "EscapedBranchName": "develop",
   "FullBuildMetaData": "Branch.develop.Sha.commitSha",
   "FullSemVer": "1.2.3-ci.5",

diff --git a/...rovidesVariablesInContinuousDeploymentModeForStableWhenCurrentCommitIsTagged.approved.txt b/...rovidesVariablesInContinuousDeploymentModeForStableWhenCurrentCommitIsTagged.approved.txt
@@ -4,6 +4,7 @@
   "BranchName": "",
   "BuildMetaData": 5,
   "CommitDate": "2014-03-06",
+  "CustomVersion": "1.2.3",
   "EscapedBranchName": "",
   "FullBuildMetaData": "5.Sha.commitSha",
   "FullSemVer": "1.2.3+5",