Table of Contents

version.json file

You must define a version.json file in your project directory or some ancestor of it. It is common to define it in the root of your git repo.

Important: Some changes to version.json are not effective until you commit the change. Pushing your commit to a remote is not necessary.

Here is the content of a sample version.json file you may start with:

{
  "$schema": "https://raw.githubusercontent.com/dotnet/Nerdbank.GitVersioning/main/src/NerdBank.GitVersioning/version.schema.json",
  "version": "1.0-beta"
}

The $schema field is optional but highly encouraged as it causes most JSON editors to add auto-completion and doc tips to help you author the file.

Note that the capitalization of the version.json filename must be all lower-case when added to the git repo.

File format

The content of the version.json file is a JSON serialized object with these properties (and more):

{
  "version": "x.y-prerelease", // required (unless the "inherit" field is set to true and a parent version.json file sets this.)
  "assemblyVersion": {
    "version": "x.y", // optional. Use when x.y for AssemblyVersionAttribute differs from the default version property.
    "precision": "revision" // optional. Use when you want a more precise assembly version than the default major.minor.
  },
  "versionHeightOffset": "zOffset", // optional. Use when you need to add/subtract a fixed value from the computed version height.
  "versionHeightOffsetAppliesTo": "x.y-prerelease", // optional. Specifies the version to which versionHeightOffset applies. When the version changes such that version height would reset, and this doesn't match the new version, versionHeightOffset is ignored.
  "semVer1NumericIdentifierPadding": 4, // optional. Use when your -prerelease includes numeric identifiers and need semver1 support.
  "gitCommitIdShortFixedLength": 10, // optional. Set the commit ID abbreviation length.
  "gitCommitIdShortAutoMinimum": 0, // optional. Set to use the short commit ID abbreviation provided by the git repository.
  "nugetPackageVersion": {
     "semVer": 1 // optional. Set to either 1 or 2 to control how the NuGet package version string is generated. Default is 1.
     "precision": "build" // optional. Use when you want to use a more or less precise package version than the default major.minor.build.
  },
  "pathFilters": [
    // optional list of paths to consider when calculating version height.
  ],
  "publicReleaseRefSpec": [
    "^refs/heads/master$", // we release out of master
    "^refs/tags/v\\d+\\.\\d+" // we also release tags starting with vN.N
  ],
  "cloudBuild": {
    "setVersionVariables": true,
    "buildNumber": {
      "enabled": false,
      "includeCommitId": {
        "when": "nonPublicReleaseOnly",
        "where": "buildMetadata"
      }
    }
  },
  "release" : {
    "tagName" : "v{version}",
    "branchName" : "v{version}",
    "versionIncrement" : "minor",
    "firstUnstableTag" : "alpha"
  },
  "inherit": false, // optional. Set to true in secondary version.json files used to tweak settings for subsets of projects.
  "prerelease": "beta" // optional. Only valid when inherit is true. Adds or overrides the prerelease tag of the inherited version.
}

The x and y variables are for your use to specify a version that is meaningful to your customers. Consider using semantic versioning for guidance. You may optionally supply a third integer in the version (i.e. x.y.z), in which case the git version height is specified as the fourth integer, which only appears in certain version representations. Alternatively, you can include the git version height in the -prerelease tag using syntax such as: 1.2.3-beta.{height}

The optional -prerelease tag allows you to indicate that you are building prerelease software.

The publicReleaseRefSpec field causes builds out of certain branches or tags to automatically drop the -gabc123 git commit ID suffix from the version, making it convenient to build releases out of these refs with a friendly version number that assumes linear versioning.

When the cloudBuild.buildNumber.includeCommitId.where property is set to fourthVersionComponent, the first 15 bits of the commit hash is used to create the 4th integer in the version number.

Version Height Offset

The versionHeightOffset property allows you to add or subtract a fixed value from the git version height. This is typically used as a temporary workaround when migrating from another versioning system or when correcting version numbering discrepancies.

The versionHeightOffsetAppliesTo property can be used in conjunction with versionHeightOffset to ensure that the offset is only applied when the version matches a specific value. When the version property changes such that the version height would be reset, and versionHeightOffsetAppliesTo does not match the new version, the versionHeightOffset will be automatically ignored.

This allows version height offsets to implicitly reset as intended when the version changes, without having to manually remove the offset properties from all version.json files in the repository.

Example

{
  "version": "1.0-beta",
  "versionHeightOffset": 100,
  "versionHeightOffsetAppliesTo": "1.0-beta"
}

In this example, the offset of 100 will be applied as long as the version remains "1.0-beta". When you update the version to "1.1-alpha" (which would reset the version height), the offset will be automatically ignored because "1.1-alpha" does not match "1.0-beta".

Note

This feature is particularly useful when a version.json file uses "inherit": true to get the version from a parent version.json file higher in the source tree. In such cases, you can set versionHeightOffset and versionHeightOffsetAppliesTo in the inheriting file without having to update it when the parent version changes. The offset will automatically stop applying when the inherited version no longer matches versionHeightOffsetAppliesTo.

Prerelease Tag in Inheriting Files

The prerelease property allows a version.json file that inherits from a parent to add or override the prerelease tag without duplicating the version number. This is particularly useful when you want to publish an "unstable" prerelease from a stable branch, or when one package is still considered unstable while its peers are already stable.

Usage Rules

  • The prerelease property can only be used when "inherit": true is set.
  • The version property in the inheriting file must not include a prerelease tag (the -suffix part).
  • Setting "prerelease": "beta" will append -beta to the inherited version.
  • Setting "prerelease": "" (empty string) will explicitly suppress any prerelease tag inherited from the parent.
  • Omitting the prerelease property will inherit the prerelease tag as-is from the parent.

Examples

Example 1: Adding a prerelease tag to a stable inherited version

Parent version.json at repository root:

{
  "$schema": "https://raw.githubusercontent.com/dotnet/Nerdbank.GitVersioning/main/src/NerdBank.GitVersioning/version.schema.json",
  "version": "1.2"
}

Child version.json in a subdirectory (e.g., src/ExperimentalPackage/version.json):

{
  "$schema": "https://raw.githubusercontent.com/dotnet/Nerdbank.GitVersioning/main/src/NerdBank.GitVersioning/version.schema.json",
  "inherit": true,
  "prerelease": "beta"
}

Result: The subdirectory will use version 1.2-beta while the rest of the repository uses 1.2.

Example 2: Suppressing an inherited prerelease tag

Parent version.json at repository root:

{
  "$schema": "https://raw.githubusercontent.com/dotnet/Nerdbank.GitVersioning/main/src/NerdBank.GitVersioning/version.schema.json",
  "version": "1.2-alpha"
}

Child version.json in a subdirectory (e.g., src/StablePackage/version.json):

{
  "$schema": "https://raw.githubusercontent.com/dotnet/Nerdbank.GitVersioning/main/src/NerdBank.GitVersioning/version.schema.json",
  "inherit": true,
  "prerelease": ""
}

Result: The subdirectory will use version 1.2 (stable) while the rest of the repository uses 1.2-alpha.

Example 3: Inheriting the prerelease tag as-is

Parent version.json at repository root:

{
  "$schema": "https://raw.githubusercontent.com/dotnet/Nerdbank.GitVersioning/main/src/NerdBank.GitVersioning/version.schema.json",
  "version": "1.2-rc"
}

Child version.json in a subdirectory:

{
  "$schema": "https://raw.githubusercontent.com/dotnet/Nerdbank.GitVersioning/main/src/NerdBank.GitVersioning/version.schema.json",
  "inherit": true
}

Result: The subdirectory will inherit and use version 1.2-rc from the parent.

Learn more about pathFilters.

Edit this page