version.json

A project version descriptor file used by Nerdbank.GitVersioning

Type object
File match version.json
Schema URL https://catalog.lintel.tools/schemas/schemastore/version-json/latest.json
Source https://raw.githubusercontent.com/dotnet/Nerdbank.GitVersioning/master/src/NerdBank.GitVersioning/version.schema.json

Validate with Lintel

npx @lintel/lintel check
Type: object

Any of

1. baseFile
2. inheritingFile

Definitions

baseFile
inheritingFile
allProperties
version string

The major.minor-pre version to use as the basis for version calculations. If {height} is not used in this value and the value has fewer than the full major.minor.build.revision specified, ".{height}" will be appended by the build.

pattern=^v?(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)(?:\.(0|[1-9][0-9]*)(?:\.(0|[1-9][0-9]*))?)?(-(?:[0-9a-zA-Z\-]+|\{height\})(?:\.(?:[0-9a-zA-Z\-]+|\{height\}))*)?(\+(?:[0-9a-zA-Z\-]+|\{height\})(?:\.(?:[0-9a-zA-Z\-]+|\{height\}))*)?$
inherit boolean

A value indicating whether this file only partially describes the versioning policy, and that more information should be discovered in an ancestor directory.

Default: false
assemblyVersion twoToFourComponentVersion | object | object

The a.b[.c[.d]] version to use particularly for the AssemblyVersionAttribute instead of the default. This is useful when maintaining assembly binding compatibility on the desktop .NET Framework is important even though AssemblyFileVersion may change.

versionHeightOffset integer

A number to add to the git height when calculating the version height (which typically appears as the 3rd integer in a computed version). May be negative, but not of greater magnitude than the original git height.

Default: 0
versionHeightOffsetAppliesTo string

The version to which the versionHeightOffset applies. When the version property changes such that the version height would be reset, and this property does not match the new version, the versionHeightOffset will be ignored. This allows the offset to implicitly reset as intended without having to manually remove it from all version.json files.

pattern=^v?(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)(?:\.(0|[1-9][0-9]*)(?:\.(0|[1-9][0-9]*))?)?(-(?:[0-9a-zA-Z\-]+|\{height\})(?:\.(?:[0-9a-zA-Z\-]+|\{height\}))*)?(\+(?:[0-9a-zA-Z\-]+|\{height\})(?:\.(?:[0-9a-zA-Z\-]+|\{height\}))*)?$
buildNumberOffset integer

OBSOLETE by v3.0. Use "versionHeightOffset" instead. A number to add to the git height when calculating the version height (which typically appears as the 3rd integer in a computed version). May be negative, but not of greater magnitude than the original git height.

Default: 0
semVer1NumericIdentifierPadding integer

The minimum number of digits to use for numeric identifiers in SemVer 1.

Default: 4
min=1max=6
gitCommitIdShortFixedLength integer

The fixed number of characters to use for the commit ID abbreviation length. This property is ignored if the gitCommitIdShortAutoMinimum property is greater than 0.

Default: 10
max=40
gitCommitIdPrefix string

The git commit prefix (e.g. 'g') in non-public release versions.

Default: "g"
pattern=^[^0-9][0-9a-zA-Z\-_\.]*$
gitCommitIdShortAutoMinimum integer

When greater than 0, the length of the commit ID will be either this value or the shortest unambiguous git-abbreviated commit ID possible, whichever is greater. When 0, the gitCommitIdShortFixedLength property is used instead.

Default: 0
max=40
nugetPackageVersion object

Details for how and what the generated version for NuGet packages will be.

2 nested properties
semVer integer

The version of SemVer (e.g. 1 or 2) that should be used when generating the package version.

Default: 1
min=1max=2
precision string

Specifies the number of components to include in the NuGet package version.

Default: "build"
Values: "major" "minor" "build" "revision"
publicReleaseRefSpec string[]

An array of regular expressions that may match a ref (branch or tag) that should be built with PublicRelease=true as the default value. The ref matched against is in its canonical form (e.g. refs/heads/master).

uniqueItems=true
cloudBuild object

Options that are applicable specifically to cloud builds (e.g. VSTS, AppVeyor, TeamCity).

3 nested properties
setAllVariables boolean

Elevates all build properties to cloud build variables prefaced with "NBGV_".

Default: false
setVersionVariables boolean

Elevate certain calculated version build properties to cloud build variables.

Default: true
buildNumber object

Override the build number preset by the cloud build with one enriched with version information.

2 nested properties
enabled boolean

Whether to override the build number preset by the cloud build.

Default: false
includeCommitId object

Describes when and where to include information about the git commit being built.

release object

Settings for the prepare-release and tag commands.

4 nested properties
tagName string

Defines the format of tag names. Format must include a placeholder '{version}' for the version.

Default: "v{version}"
pattern=\{version\}
branchName string

Defines the format of release branch names. Format must include a placeholder '{version}' for the version.

Default: "v{version}"
pattern=\{version\}
versionIncrement string

Specifies which part of the version on the current branch is incremented when preparing a release.

Default: "minor"
Values: "major" "minor" "build"
firstUnstableTag string

Specifies the first/default prerelease tag for new versions.

Default: "alpha"
pathFilters string[]

An array of pathspec-like strings that are used to filter commits when calculating the version height. A commit will not increment the version height if its changed files are not included by these filters. Paths are relative to this file. Paths relative to the root of the repository can be specified with the :/ prefix. Exclusions can be specified with a :^ prefix for relative paths, or a :^/ prefix for paths relative to the root of the repository. After a path matches any non-exclude filter, it will be run through all exclude filters. If it matches, the path is ignored.

uniqueItems=true
inheritingProperties
prerelease string

A prerelease tag to append to the version inherited from a parent version.json file. This property can only be used when 'inherit' is true and the 'version' property does not include a prerelease tag. Set to an empty string to explicitly suppress an inherited prerelease tag. Omit this property to inherit the prerelease tag as-is from the parent.

pattern=^[0-9a-zA-Z\-]*$
twoToFourComponentVersion string

A major.minor[.build[.revision]] version (2-4 version components).