From 163f851eedc7d7b1e6f97ea7f129a2a223427b9b Mon Sep 17 00:00:00 2001 From: Artur Stolear Date: Wed, 19 Aug 2026 23:15:26 +0200 Subject: [PATCH 1/2] feat: generate nested v7 configuration schema --- schemas/7.0/GitVersion.configuration.json | 808 +++++++++++----------- src/GitVersion.Schema/Extensions.cs | 102 ++- src/GitVersion.Schema/Program.cs | 9 +- 3 files changed, 517 insertions(+), 402 deletions(-) diff --git a/schemas/7.0/GitVersion.configuration.json b/schemas/7.0/GitVersion.configuration.json index 4468d2f059..e980418549 100644 --- a/schemas/7.0/GitVersion.configuration.json +++ b/schemas/7.0/GitVersion.configuration.json @@ -5,414 +5,439 @@ "description": "GitVersion configuration schema (7.0)", "type": "object", "properties": { - "assembly-file-versioning-format": { - "description": "Specifies the format of AssemblyFileVersion and overwrites the value of assembly-file-versioning-scheme.", - "type": [ - "null", - "string" - ] - }, - "assembly-file-versioning-scheme": { - "description": "The scheme to use when setting AssemblyFileVersion attribute. Can be 'MajorMinorPatchTag', 'MajorMinorPatch', 'MajorMinor', 'Major', 'None'. Defaults to 'MajorMinorPatch'.", - "default": "MajorMinorPatch", - "enum": [ - "MajorMinorPatchTag", - "MajorMinorPatch", - "MajorMinor", - "Major", - "None", - null - ] - }, - "assembly-informational-format": { - "description": "Specifies the format of AssemblyInformationalVersion. Defaults to '{InformationalVersion}'.", - "default": "'{InformationalVersion}'", - "type": [ - "null", - "string" - ] - }, - "assembly-versioning-format": { - "description": "Specifies the format of AssemblyVersion and overwrites the value of assembly-versioning-scheme.", - "type": [ - "null", - "string" - ] - }, - "assembly-versioning-scheme": { - "description": "The scheme to use when setting AssemblyVersion attribute. Can be 'MajorMinorPatchTag', 'MajorMinorPatch', 'MajorMinor', 'Major', 'None'. Defaults to 'MajorMinorPatch'.", - "default": "MajorMinorPatch", - "enum": [ - "MajorMinorPatchTag", - "MajorMinorPatch", - "MajorMinor", - "Major", - "None", - null - ] - }, - "branches": { - "description": "The header for all the individual branch configuration.", + "calculation": { + "description": "Settings that participate in semantic-version calculation.", "type": "object", - "additionalProperties": { - "type": "object", - "properties": { - "commit-message-incrementing": { - "description": "Sets whether it should be possible to increment the version with special syntax in the commit message. Can be 'Disabled', 'Enabled' or 'MergeMessageOnly'.", - "enum": [ - "Enabled", - "Disabled", - "MergeMessageOnly", - null - ] - }, - "custom-version-format": { - "description": "Specifies the format of CustomVersion.", - "type": [ - "null", - "string" - ] - }, - "increment": { - "description": "The increment strategy for this branch. Can be 'Inherit', 'Patch', 'Minor', 'Major', 'None'.", - "$ref": "#/$defs/incrementStrategy" - }, - "is-main-branch": { - "description": "When using Mainline mode, this indicates that this branch is a mainline. By default main and support/* are mainlines.", - "type": [ - "null", - "boolean" - ] - }, - "is-release-branch": { - "description": "Indicates this branch configuration represents a release branch in GitFlow.", - "type": [ - "null", - "boolean" - ] - }, - "is-source-branch-for": { - "description": "The branches that this branch is a source branch.", - "$ref": "#/$defs/hashSetOfString" - }, - "label": { - "description": "The label to use for this branch. Use the value {BranchName} or similar as a placeholder to insert a named capture group from RegularExpression (fx. the branch name).", - "type": [ - "null", - "string" - ] - }, - "mode": { - "description": "The deployment mode for this branch. Can be 'ManualDeployment', 'ContinuousDelivery', 'ContinuousDeployment'.", + "properties": { + "branches": { + "description": "The header for all the individual branch configuration.", + "type": "object", + "additionalProperties": { + "type": "object", + "properties": { + "commit-message-incrementing": { + "description": "Sets whether it should be possible to increment the version with special syntax in the commit message. Can be 'Disabled', 'Enabled' or 'MergeMessageOnly'.", + "enum": [ + "Enabled", + "Disabled", + "MergeMessageOnly", + null + ] + }, + "increment": { + "description": "The increment strategy for this branch. Can be 'Inherit', 'Patch', 'Minor', 'Major', 'None'.", + "$ref": "#/$defs/incrementStrategy" + }, + "is-main-branch": { + "description": "When using Mainline mode, this indicates that this branch is a mainline. By default main and support/* are mainlines.", + "type": [ + "null", + "boolean" + ] + }, + "is-release-branch": { + "description": "Indicates this branch configuration represents a release branch in GitFlow.", + "type": [ + "null", + "boolean" + ] + }, + "is-source-branch-for": { + "description": "The branches that this branch is a source branch.", + "$ref": "#/$defs/hashSetOfString" + }, + "label": { + "description": "The label to use for this branch. Use the value {BranchName} or similar as a placeholder to insert a named capture group from RegularExpression (fx. the branch name).", + "type": [ + "null", + "string" + ] + }, + "mode": { + "description": "The deployment mode for this branch. Can be 'ManualDeployment', 'ContinuousDelivery', 'ContinuousDeployment'.", + "enum": [ + "ManualDeployment", + "ContinuousDelivery", + "ContinuousDeployment", + null + ] + }, + "prevent-increment": { + "description": "The prevent increment configuration section.", + "$ref": "#/$defs/preventIncrementConfiguration" + }, + "regex": { + "format": "regex", + "description": "The regular expression pattern to use to match this branch. Matching is case-insensitive by default; use (?-i) to enable case-sensitive matching.", + "type": [ + "null", + "string" + ] + }, + "source-branches": { + "description": "The source branches for this branch.", + "$ref": "#/$defs/hashSetOfString" + }, + "track-merge-message": { + "description": "This property is a branch related property and gives the user the possibility to control the behavior of whether the merge commit message will be interpreted as a next version or not.", + "type": [ + "null", + "boolean" + ] + }, + "track-merge-target": { + "description": "Strategy which will look for tagged merge commits directly off the current branch.", + "type": [ + "null", + "boolean" + ] + }, + "tracks-release-branches": { + "description": "Indicates this branch configuration represents develop in GitFlow.", + "type": [ + "null", + "boolean" + ] + } + }, + "additionalProperties": false + } + }, + "commit-message-incrementing": { + "description": "Sets whether it should be possible to increment the version with special syntax in the commit message. Can be 'Disabled', 'Enabled' or 'MergeMessageOnly'.", + "enum": [ + "Enabled", + "Disabled", + "MergeMessageOnly", + null + ] + }, + "ignore": { + "description": "The header property for the ignore configuration.", + "type": "object", + "properties": { + "branches": { + "description": "A sequence of regular expressions matching branch names without the remote prefix to be excluded as version sources. Matching is case-insensitive by default; use (?-i) to enable case-sensitive matching.", + "$ref": "#/$defs/hashSetOfString" + }, + "commits-before": { + "format": "date-time", + "description": "Commits before this date will be ignored. Format: yyyy-MM-ddTHH:mm:ss.", + "type": [ + "null", + "string" + ] + }, + "paths": { + "description": "A sequence of regular expressions matching file paths to be excluded from the version calculations. Matching is case-insensitive by default; use (?-i) to enable case-sensitive matching.", + "$ref": "#/$defs/hashSetOfString" + }, + "sha": { + "description": "A sequence of SHAs to be excluded from the version calculations.", + "$ref": "#/$defs/hashSetOfString" + }, + "tags": { + "description": "A sequence of regular expressions matching friendly tag names to be excluded as version sources. Matching is case-insensitive by default; use (?-i) to enable case-sensitive matching.", + "$ref": "#/$defs/hashSetOfString" + } + } + }, + "increment": { + "description": "The increment strategy for this branch. Can be 'Inherit', 'Patch', 'Minor', 'Major', 'None'.", + "$ref": "#/$defs/incrementStrategy" + }, + "is-main-branch": { + "description": "When using Mainline mode, this indicates that this branch is a mainline. By default main and support/* are mainlines.", + "type": [ + "null", + "boolean" + ] + }, + "is-release-branch": { + "description": "Indicates this branch configuration represents a release branch in GitFlow.", + "type": [ + "null", + "boolean" + ] + }, + "is-source-branch-for": { + "description": "The branches that this branch is a source branch.", + "$ref": "#/$defs/hashSetOfString" + }, + "label": { + "description": "The label to use for this branch. Use the value {BranchName} or similar as a placeholder to insert a named capture group from RegularExpression (fx. the branch name).", + "type": [ + "null", + "string" + ] + }, + "major-version-bump-message": { + "format": "regex", + "description": "The regular expression to match commit messages with to perform a major version increment. Defaults to '[+=]semver:\\s?(breaking|major)'. Matching is case-insensitive by default; use (?-i) to enable case-sensitive matching.", + "default": "[+=]semver:\\s?(breaking|major)", + "type": [ + "null", + "string" + ] + }, + "merge-message-formats": { + "description": "Custom regular expression merge message formats to enable identification of merge messages that do not follow the built-in conventions. Matching is case-insensitive by default; use (?-i) to enable case-sensitive matching.", + "type": "object", + "additionalProperties": { + "type": "string" + } + }, + "minor-version-bump-message": { + "format": "regex", + "description": "The regular expression to match commit messages with to perform a minor version increment. Defaults to '[+=]semver:\\s?(feature|minor)'. Matching is case-insensitive by default; use (?-i) to enable case-sensitive matching.", + "default": "[+=]semver:\\s?(feature|minor)", + "type": [ + "null", + "string" + ] + }, + "mode": { + "description": "The deployment mode for this branch. Can be 'ManualDeployment', 'ContinuousDelivery', 'ContinuousDeployment'.", + "enum": [ + "ManualDeployment", + "ContinuousDelivery", + "ContinuousDeployment", + null + ] + }, + "next-version": { + "description": "Allows you to bump the next version explicitly. Useful for bumping main or a feature branch with breaking changes", + "type": [ + "null", + "string" + ] + }, + "no-bump-message": { + "format": "regex", + "description": "Used to tell GitVersion not to increment when in Mainline development mode. Defaults to '[+=]semver:\\s?(none|skip)'. Matching is case-insensitive by default; use (?-i) to enable case-sensitive matching.", + "default": "[+=]semver:\\s?(none|skip)", + "type": [ + "null", + "string" + ] + }, + "patch-version-bump-message": { + "format": "regex", + "description": "The regular expression to match commit messages with to perform a patch version increment. Defaults to '[+=]semver:\\s?(fix|patch)'. Matching is case-insensitive by default; use (?-i) to enable case-sensitive matching.", + "default": "[+=]semver:\\s?(fix|patch)", + "type": [ + "null", + "string" + ] + }, + "prevent-increment": { + "description": "The prevent increment configuration section.", + "$ref": "#/$defs/preventIncrementConfiguration" + }, + "regex": { + "format": "regex", + "description": "The regular expression pattern to use to match this branch. Matching is case-insensitive by default; use (?-i) to enable case-sensitive matching.", + "type": [ + "null", + "string" + ] + }, + "semantic-version-format": { + "description": "Specifies the semantic version format that is used when parsing the string. Can be 'Strict' or 'Loose'. Defaults to 'Strict'.", + "default": "Strict", + "enum": [ + "Strict", + "Loose" + ] + }, + "source-branches": { + "description": "The source branches for this branch.", + "$ref": "#/$defs/hashSetOfString" + }, + "strategies": { + "description": "Specifies which version strategies (one or more) will be used to determine the next version. Following values are available: 'ConfiguredNextVersion', 'MergeMessage', 'TaggedCommit', 'TrackReleaseBranches', 'VersionInBranchName' and 'Mainline'.", + "type": "array", + "items": { "enum": [ - "ManualDeployment", - "ContinuousDelivery", - "ContinuousDeployment", - null - ] - }, - "pre-release-weight": { - "description": "Provides a way to translate the PreReleaseLabelName to a number.", - "type": [ - "null", - "integer" - ] - }, - "prevent-increment": { - "description": "The prevent increment configuration section.", - "$ref": "#/$defs/preventIncrementConfiguration" - }, - "regex": { - "format": "regex", - "description": "The regular expression pattern to use to match this branch. Matching is case-insensitive by default; use (?-i) to enable case-sensitive matching.", - "type": [ - "null", - "string" - ] - }, - "source-branches": { - "description": "The source branches for this branch.", - "$ref": "#/$defs/hashSetOfString" - }, - "track-merge-message": { - "description": "This property is a branch related property and gives the user the possibility to control the behavior of whether the merge commit message will be interpreted as a next version or not.", - "type": [ - "null", - "boolean" - ] - }, - "track-merge-target": { - "description": "Strategy which will look for tagged merge commits directly off the current branch.", - "type": [ - "null", - "boolean" - ] - }, - "tracks-release-branches": { - "description": "Indicates this branch configuration represents develop in GitFlow.", - "type": [ - "null", - "boolean" + "None", + "Fallback", + "ConfiguredNextVersion", + "MergeMessage", + "TaggedCommit", + "TrackReleaseBranches", + "VersionInBranchName", + "Mainline" ] } + }, + "tag-prefix": { + "format": "regex", + "description": "A regular expression which is used to trim Git tags before processing. Defaults to '[vV]?'. Matching is case-insensitive by default; use (?-i) to enable case-sensitive matching.", + "default": "[vV]?", + "type": [ + "null", + "string" + ] + }, + "track-merge-message": { + "description": "This property is a branch related property and gives the user the possibility to control the behavior of whether the merge commit message will be interpreted as a next version or not.", + "type": [ + "null", + "boolean" + ] + }, + "track-merge-target": { + "description": "Strategy which will look for tagged merge commits directly off the current branch.", + "type": [ + "null", + "boolean" + ] + }, + "tracks-release-branches": { + "description": "Indicates this branch configuration represents develop in GitFlow.", + "type": [ + "null", + "boolean" + ] + }, + "version-bump-reset-message": { + "format": "regex", + "description": "The regular expression to match commit messages that reset the version bump baseline and suppress the configured branch increment. Defaults to '=semver:'. Matching is case-insensitive by default; use (?-i) to enable case-sensitive matching.", + "default": "=semver:", + "type": [ + "null", + "string" + ] + }, + "version-in-branch-pattern": { + "format": "regex", + "description": "A regular expression which is used to determine the version number in the branch name or commit message (e.g., v1.0.0-LTS). Defaults to '(?[vV]?\\d+(\\.\\d+)?(\\.\\d+)?).*'. Matching is case-insensitive by default; use (?-i) to enable case-sensitive matching.", + "default": "(?[vV]?\\d+(\\.\\d+)?(\\.\\d+)?).*", + "type": [ + "null", + "string" + ] + }, + "workflow": { + "description": "The base template of the configuration to use. Possible values are: 'GitFlow/v1' or 'GitHubFlow/v1'", + "type": [ + "null", + "string" + ] } - } + }, + "additionalProperties": false }, - "commit-date-format": { - "description": "The format to use when calculating the commit date. Defaults to 'yyyy-MM-dd'. See [Standard Date and Time Format Strings](https://learn.microsoft.com/en-us/dotnet/standard/base-types/standard-date-and-time-format-strings) and [Custom Date and Time Format Strings](https://learn.microsoft.com/en-us/dotnet/standard/base-types/standard-date-and-time-format-strings).", - "default": "yyyy-MM-dd", - "type": [ - "null", - "string" - ] - }, - "commit-message-incrementing": { - "description": "Sets whether it should be possible to increment the version with special syntax in the commit message. Can be 'Disabled', 'Enabled' or 'MergeMessageOnly'.", - "enum": [ - "Enabled", - "Disabled", - "MergeMessageOnly", - null - ] - }, - "custom-version-format": { - "description": "Specifies the format of CustomVersion.", - "type": [ - "null", - "string" - ] - }, - "ignore": { - "description": "The header property for the ignore configuration.", + "output": { + "description": "Settings that affect assembly, build-server, and formatted version output.", "type": "object", "properties": { + "assembly-file-versioning-format": { + "description": "Specifies the format of AssemblyFileVersion and overwrites the value of assembly-file-versioning-scheme.", + "type": [ + "null", + "string" + ] + }, + "assembly-file-versioning-scheme": { + "description": "The scheme to use when setting AssemblyFileVersion attribute. Can be 'MajorMinorPatchTag', 'MajorMinorPatch', 'MajorMinor', 'Major', 'None'. Defaults to 'MajorMinorPatch'.", + "default": "MajorMinorPatch", + "enum": [ + "MajorMinorPatchTag", + "MajorMinorPatch", + "MajorMinor", + "Major", + "None", + null + ] + }, + "assembly-informational-format": { + "description": "Specifies the format of AssemblyInformationalVersion. Defaults to '{InformationalVersion}'.", + "default": "'{InformationalVersion}'", + "type": [ + "null", + "string" + ] + }, + "assembly-versioning-format": { + "description": "Specifies the format of AssemblyVersion and overwrites the value of assembly-versioning-scheme.", + "type": [ + "null", + "string" + ] + }, + "assembly-versioning-scheme": { + "description": "The scheme to use when setting AssemblyVersion attribute. Can be 'MajorMinorPatchTag', 'MajorMinorPatch', 'MajorMinor', 'Major', 'None'. Defaults to 'MajorMinorPatch'.", + "default": "MajorMinorPatch", + "enum": [ + "MajorMinorPatchTag", + "MajorMinorPatch", + "MajorMinor", + "Major", + "None", + null + ] + }, "branches": { - "description": "A sequence of regular expressions matching branch names without the remote prefix to be excluded as version sources. Matching is case-insensitive by default; use (?-i) to enable case-sensitive matching.", - "$ref": "#/$defs/hashSetOfString" + "description": "The header for all the individual branch configuration.", + "type": "object", + "additionalProperties": { + "type": "object", + "properties": { + "custom-version-format": { + "description": "Specifies the format of CustomVersion.", + "type": [ + "null", + "string" + ] + }, + "pre-release-weight": { + "description": "Provides a way to translate the PreReleaseLabelName to a number.", + "type": [ + "null", + "integer" + ] + } + }, + "additionalProperties": false + } }, - "commits-before": { - "format": "date-time", - "description": "Commits before this date will be ignored. Format: yyyy-MM-ddTHH:mm:ss.", + "commit-date-format": { + "description": "The format to use when calculating the commit date. Defaults to 'yyyy-MM-dd'. See [Standard Date and Time Format Strings](https://learn.microsoft.com/en-us/dotnet/standard/base-types/standard-date-and-time-format-strings) and [Custom Date and Time Format Strings](https://learn.microsoft.com/en-us/dotnet/standard/base-types/standard-date-and-time-format-strings).", + "default": "yyyy-MM-dd", "type": [ "null", "string" ] }, - "paths": { - "description": "A sequence of regular expressions matching file paths to be excluded from the version calculations. Matching is case-insensitive by default; use (?-i) to enable case-sensitive matching.", - "$ref": "#/$defs/hashSetOfString" + "custom-version-format": { + "description": "Specifies the format of CustomVersion.", + "type": [ + "null", + "string" + ] }, - "sha": { - "description": "A sequence of SHAs to be excluded from the version calculations.", - "$ref": "#/$defs/hashSetOfString" + "pre-release-weight": { + "description": "Provides a way to translate the PreReleaseLabelName to a number.", + "type": [ + "null", + "integer" + ] }, - "tags": { - "description": "A sequence of regular expressions matching friendly tag names to be excluded as version sources. Matching is case-insensitive by default; use (?-i) to enable case-sensitive matching.", - "$ref": "#/$defs/hashSetOfString" + "tag-pre-release-weight": { + "description": "The pre-release weight in case of tagged commits. Defaults to 60000.", + "type": [ + "null", + "integer" + ] + }, + "update-build-number": { + "description": "Whether to update the build number in the project file. Defaults to true.", + "default": "true", + "type": "boolean" } - } - }, - "increment": { - "description": "The increment strategy for this branch. Can be 'Inherit', 'Patch', 'Minor', 'Major', 'None'.", - "$ref": "#/$defs/incrementStrategy" - }, - "is-main-branch": { - "description": "When using Mainline mode, this indicates that this branch is a mainline. By default main and support/* are mainlines.", - "type": [ - "null", - "boolean" - ] - }, - "is-release-branch": { - "description": "Indicates this branch configuration represents a release branch in GitFlow.", - "type": [ - "null", - "boolean" - ] - }, - "is-source-branch-for": { - "description": "The branches that this branch is a source branch.", - "$ref": "#/$defs/hashSetOfString" - }, - "label": { - "description": "The label to use for this branch. Use the value {BranchName} or similar as a placeholder to insert a named capture group from RegularExpression (fx. the branch name).", - "type": [ - "null", - "string" - ] - }, - "major-version-bump-message": { - "format": "regex", - "description": "The regular expression to match commit messages with to perform a major version increment. Defaults to '[+=]semver:\\s?(breaking|major)'. Matching is case-insensitive by default; use (?-i) to enable case-sensitive matching.", - "default": "[+=]semver:\\s?(breaking|major)", - "type": [ - "null", - "string" - ] - }, - "merge-message-formats": { - "description": "Custom regular expression merge message formats to enable identification of merge messages that do not follow the built-in conventions. Matching is case-insensitive by default; use (?-i) to enable case-sensitive matching.", - "type": "object", - "additionalProperties": { - "type": "string" - } - }, - "minor-version-bump-message": { - "format": "regex", - "description": "The regular expression to match commit messages with to perform a minor version increment. Defaults to '[+=]semver:\\s?(feature|minor)'. Matching is case-insensitive by default; use (?-i) to enable case-sensitive matching.", - "default": "[+=]semver:\\s?(feature|minor)", - "type": [ - "null", - "string" - ] - }, - "mode": { - "description": "The deployment mode for this branch. Can be 'ManualDeployment', 'ContinuousDelivery', 'ContinuousDeployment'.", - "enum": [ - "ManualDeployment", - "ContinuousDelivery", - "ContinuousDeployment", - null - ] - }, - "next-version": { - "description": "Allows you to bump the next version explicitly. Useful for bumping main or a feature branch with breaking changes", - "type": [ - "null", - "string" - ] - }, - "no-bump-message": { - "format": "regex", - "description": "Used to tell GitVersion not to increment when in Mainline development mode. Defaults to '[+=]semver:\\s?(none|skip)'. Matching is case-insensitive by default; use (?-i) to enable case-sensitive matching.", - "default": "[+=]semver:\\s?(none|skip)", - "type": [ - "null", - "string" - ] - }, - "patch-version-bump-message": { - "format": "regex", - "description": "The regular expression to match commit messages with to perform a patch version increment. Defaults to '[+=]semver:\\s?(fix|patch)'. Matching is case-insensitive by default; use (?-i) to enable case-sensitive matching.", - "default": "[+=]semver:\\s?(fix|patch)", - "type": [ - "null", - "string" - ] - }, - "pre-release-weight": { - "description": "Provides a way to translate the PreReleaseLabelName to a number.", - "type": [ - "null", - "integer" - ] - }, - "prevent-increment": { - "description": "The prevent increment configuration section.", - "$ref": "#/$defs/preventIncrementConfiguration" - }, - "regex": { - "format": "regex", - "description": "The regular expression pattern to use to match this branch. Matching is case-insensitive by default; use (?-i) to enable case-sensitive matching.", - "type": [ - "null", - "string" - ] - }, - "semantic-version-format": { - "description": "Specifies the semantic version format that is used when parsing the string. Can be 'Strict' or 'Loose'. Defaults to 'Strict'.", - "default": "Strict", - "enum": [ - "Strict", - "Loose" - ] - }, - "source-branches": { - "description": "The source branches for this branch.", - "$ref": "#/$defs/hashSetOfString" - }, - "strategies": { - "description": "Specifies which version strategies (one or more) will be used to determine the next version. Following values are available: 'ConfiguredNextVersion', 'MergeMessage', 'TaggedCommit', 'TrackReleaseBranches', 'VersionInBranchName' and 'Mainline'.", - "type": "array", - "items": { - "enum": [ - "None", - "Fallback", - "ConfiguredNextVersion", - "MergeMessage", - "TaggedCommit", - "TrackReleaseBranches", - "VersionInBranchName", - "Mainline" - ] - } - }, - "tag-pre-release-weight": { - "description": "The pre-release weight in case of tagged commits. Defaults to 60000.", - "type": [ - "null", - "integer" - ] - }, - "tag-prefix": { - "format": "regex", - "description": "A regular expression which is used to trim Git tags before processing. Defaults to '[vV]?'. Matching is case-insensitive by default; use (?-i) to enable case-sensitive matching.", - "default": "[vV]?", - "type": [ - "null", - "string" - ] - }, - "track-merge-message": { - "description": "This property is a branch related property and gives the user the possibility to control the behavior of whether the merge commit message will be interpreted as a next version or not.", - "type": [ - "null", - "boolean" - ] - }, - "track-merge-target": { - "description": "Strategy which will look for tagged merge commits directly off the current branch.", - "type": [ - "null", - "boolean" - ] - }, - "tracks-release-branches": { - "description": "Indicates this branch configuration represents develop in GitFlow.", - "type": [ - "null", - "boolean" - ] - }, - "update-build-number": { - "description": "Whether to update the build number in the project file. Defaults to true.", - "default": "true", - "type": "boolean" - }, - "version-bump-reset-message": { - "format": "regex", - "description": "The regular expression to match commit messages that reset the version bump baseline and suppress the configured branch increment. Defaults to '=semver:'. Matching is case-insensitive by default; use (?-i) to enable case-sensitive matching.", - "default": "=semver:", - "type": [ - "null", - "string" - ] - }, - "version-in-branch-pattern": { - "format": "regex", - "description": "A regular expression which is used to determine the version number in the branch name or commit message (e.g., v1.0.0-LTS). Defaults to '(?[vV]?\\d+(\\.\\d+)?(\\.\\d+)?).*'. Matching is case-insensitive by default; use (?-i) to enable case-sensitive matching.", - "default": "(?[vV]?\\d+(\\.\\d+)?(\\.\\d+)?).*", - "type": [ - "null", - "string" - ] - }, - "workflow": { - "description": "The base template of the configuration to use. Possible values are: 'GitFlow/v1' or 'GitHubFlow/v1'", - "type": [ - "null", - "string" - ] + }, + "additionalProperties": false } }, "$defs": { @@ -457,5 +482,6 @@ } } } - } + }, + "additionalProperties": false } \ No newline at end of file diff --git a/src/GitVersion.Schema/Extensions.cs b/src/GitVersion.Schema/Extensions.cs index c18e30807d..cd9b6c5ecf 100644 --- a/src/GitVersion.Schema/Extensions.cs +++ b/src/GitVersion.Schema/Extensions.cs @@ -1,4 +1,6 @@ using System.Text.Encodings.Web; +using System.Text.Json.Nodes; +using GitVersion.Configuration; using Json.More; using Json.Schema; @@ -6,25 +8,105 @@ namespace GitVersion.Schema; internal static class Extensions { + private const string AdditionalPropertiesJsonPropertyName = "additionalProperties"; + private const string PropertiesJsonPropertyName = "properties"; + extension(JsonSchema jsonSchema) { public void WriteToFile(string outputFileName, bool orderPropertiesByName = false) { - var jsonDocument = jsonSchema.ToJsonDocument(); + using var jsonDocument = jsonSchema.ToJsonDocument(); + + WriteToFile(jsonDocument, outputFileName, orderPropertiesByName); + } + + public void WriteV7ConfigurationToFile(string outputFileName) + { + using var jsonDocument = jsonSchema.ToJsonDocument(); + var schema = JsonNode.Parse(jsonDocument.RootElement.GetRawText())?.AsObject() + ?? throw new InvalidOperationException("Could not materialize the configuration schema."); + var properties = schema[PropertiesJsonPropertyName]?.AsObject() + ?? throw new InvalidOperationException("The configuration schema has no properties."); + + schema[PropertiesJsonPropertyName] = new JsonObject + { + [ConfigurationDocumentMapper.CalculationSectionName] = CreateSection(properties, output: false), + [ConfigurationDocumentMapper.OutputSectionName] = CreateSection(properties, output: true) + }; + schema[AdditionalPropertiesJsonPropertyName] = false; + + using var nestedSchema = JsonDocument.Parse(schema.ToJsonString()); + WriteToFile(nestedSchema, outputFileName, orderPropertiesByName: true); + } + } + + private static JsonObject CreateSection(JsonObject source, bool output) + { + JsonObject properties = []; + foreach (var (propertyName, propertySchema) in source) + { + if (propertySchema is null) + { + continue; + } - using var fs = File.Create(outputFileName); - using var writer = new Utf8JsonWriter(fs, new() { Indented = true, Encoder = JavaScriptEncoder.UnsafeRelaxedJsonEscaping }); - if (orderPropertiesByName) + if (propertyName == ConfigurationDocumentMapper.BranchesPropertyName) + { + properties[propertyName] = CreateBranches(propertySchema, output); + } + else if (ConfigurationDocumentMapper.IsOutputProperty(propertyName) == output) { - WriteElement(writer, jsonDocument.RootElement); + properties[propertyName] = propertySchema.DeepClone(); } - else + } + + return new JsonObject + { + ["description"] = output + ? "Settings that affect assembly, build-server, and formatted version output." + : "Settings that participate in semantic-version calculation.", + ["type"] = "object", + [PropertiesJsonPropertyName] = properties, + [AdditionalPropertiesJsonPropertyName] = false + }; + } + + private static JsonNode CreateBranches(JsonNode source, bool output) + { + var branches = source.DeepClone().AsObject(); + var branchConfiguration = branches[AdditionalPropertiesJsonPropertyName]?.AsObject() + ?? throw new InvalidOperationException("The branch configuration schema is missing."); + var branchProperties = branchConfiguration[PropertiesJsonPropertyName]?.AsObject() + ?? throw new InvalidOperationException("The branch configuration schema has no properties."); + JsonObject filteredBranchProperties = []; + foreach (var (propertyName, propertySchema) in branchProperties) + { + if (propertySchema is not null + && ConfigurationDocumentMapper.IsOutputBranchProperty(propertyName) == output) { - jsonDocument.WriteTo(writer); + filteredBranchProperties[propertyName] = propertySchema.DeepClone(); } - writer.Flush(); - fs.Flush(); } + + branchConfiguration[PropertiesJsonPropertyName] = filteredBranchProperties; + branchConfiguration[AdditionalPropertiesJsonPropertyName] = false; + return branches; + } + + private static void WriteToFile(JsonDocument jsonDocument, string outputFileName, bool orderPropertiesByName) + { + using var fs = File.Create(outputFileName); + using var writer = new Utf8JsonWriter(fs, new() { Indented = true, Encoder = JavaScriptEncoder.UnsafeRelaxedJsonEscaping }); + if (orderPropertiesByName) + { + WriteElement(writer, jsonDocument.RootElement); + } + else + { + jsonDocument.WriteTo(writer); + } + writer.Flush(); + fs.Flush(); } private static void WriteElement(Utf8JsonWriter writer, JsonElement element, bool orderMembers = false) @@ -42,7 +124,7 @@ private static void WriteElement(Utf8JsonWriter writer, JsonElement element, boo foreach (var property in properties) { writer.WritePropertyName(property.Name); - WriteElement(writer, property.Value, property.NameEquals("properties")); + WriteElement(writer, property.Value, property.NameEquals(PropertiesJsonPropertyName)); } writer.WriteEndObject(); break; diff --git a/src/GitVersion.Schema/Program.cs b/src/GitVersion.Schema/Program.cs index 2b1889db93..ee6a5a9102 100644 --- a/src/GitVersion.Schema/Program.cs +++ b/src/GitVersion.Schema/Program.cs @@ -38,7 +38,14 @@ var fileName = Path.Combine(schemasDirectory, schemaVersion, "GitVersion.configuration.json"); Console.WriteLine($"Writing schema to {fileName}"); -schema.WriteToFile(fileName, orderPropertiesByName: true); +if (Version.TryParse(schemaVersion, out var version) && version.Major >= 7) +{ + schema.WriteV7ConfigurationToFile(fileName); +} +else +{ + schema.WriteToFile(fileName, orderPropertiesByName: true); +} configuration.PropertyNameResolver = PropertyNameResolvers.AsDeclared; From 6575eeacef5babeaa77e33d15ae8adc86efbcc05 Mon Sep 17 00:00:00 2001 From: Artur Stolear Date: Wed, 19 Aug 2026 23:15:32 +0200 Subject: [PATCH 2/2] docs: document v7 configuration migration --- BREAKING_CHANGES.md | 20 ++ .../branching-strategies/gitflow/examples.md | 5 +- .../githubflow/examples.md | 5 +- docs/input/docs/migration/v6-to-v7.md | 31 ++- .../docs/reference/build-servers/gitlab.md | 11 +- docs/input/docs/reference/configuration.md | 218 +++++++++++++----- .../input/docs/reference/custom-formatting.md | 118 ++++++---- .../mdsource/configuration.source.md | 218 +++++++++++++----- .../docs/reference/version-increments.md | 22 +- docs/input/docs/usage/cli/arguments.md | 41 +++- docs/input/docs/usage/cli/assembly-patch.md | 2 +- 11 files changed, 499 insertions(+), 192 deletions(-) diff --git a/BREAKING_CHANGES.md b/BREAKING_CHANGES.md index a1a3526d12..742b730c26 100644 --- a/BREAKING_CHANGES.md +++ b/BREAKING_CHANGES.md @@ -55,6 +55,26 @@ The command-line interface has been migrated from Windows-style (`/switch` and s As a temporary migration aid, set the environment variable `GITVERSION_USE_V6_ARGUMENT_PARSER=true` to restore the legacy `/switch` and `-switch` argument handling. This escape hatch will be removed in a future release. +### Configuration structure and migration + +v7 configuration now separates calculation from output: + +```yaml +calculation: + branches: + main: + increment: Patch +output: + update-build-number: true +``` + +v7.0 defaults to the nested layout. `GITVERSION_CONFIGURATION_VERSION=v6` is a +temporary flat-layout fallback that logs a migration warning for user files. +Convert files with `gitversion config migrate`. The command +writes YAML to stdout by default, supports `--config`, `--output`, +`--in-place`, and `--force`, and warns that comments cannot be preserved when +replacing a file. + #### Full argument mapping | Old argument | New argument | Short alias | Env var alternative | diff --git a/docs/input/docs/learn/branching-strategies/gitflow/examples.md b/docs/input/docs/learn/branching-strategies/gitflow/examples.md index e320c05d39..7cae712c72 100644 --- a/docs/input/docs/learn/branching-strategies/gitflow/examples.md +++ b/docs/input/docs/learn/branching-strategies/gitflow/examples.md @@ -12,8 +12,9 @@ in GitVersion. To enable this workflow, the builtin template configuration as follows: ```yaml -workflow: GitFlow/v1 -mode: ContinuousDelivery +calculation: + mode: ContinuousDelivery + workflow: GitFlow/v1 ``` Where diff --git a/docs/input/docs/learn/branching-strategies/githubflow/examples.md b/docs/input/docs/learn/branching-strategies/githubflow/examples.md index 89936146cc..ac070328cb 100644 --- a/docs/input/docs/learn/branching-strategies/githubflow/examples.md +++ b/docs/input/docs/learn/branching-strategies/githubflow/examples.md @@ -10,8 +10,9 @@ in GitVersion. To enable this workflow, the builtin template configuration as follows: ```yaml -workflow: GitHubFlow/v1 -mode: ContinuousDelivery +calculation: + mode: ContinuousDelivery + workflow: GitHubFlow/v1 ``` Where diff --git a/docs/input/docs/migration/v6-to-v7.md b/docs/input/docs/migration/v6-to-v7.md index 6fa12f2eb2..1b8b4dd79f 100644 --- a/docs/input/docs/migration/v6-to-v7.md +++ b/docs/input/docs/migration/v6-to-v7.md @@ -117,6 +117,34 @@ gitversion --url https://github.com/org/repo.git --branch main --username user - For current command details and examples, see [CLI Arguments](/docs/usage/cli/arguments). +## Configuration migration + +GitVersion v7 stores settings under `calculation` and `output`. Convert an +existing flat v6 YAML document with the POSIX-only migration command: + +```shell +gitversion config migrate +gitversion config migrate --config GitVersion.yml --output GitVersion.v7.yml +gitversion config migrate --config GitVersion.yml --in-place +``` + +The first command discovers `GitVersion.yml` and emits v7 YAML to stdout. +`--output` requires `--force` to replace an existing file and cannot be used +with `--in-place`. In-place migration warns because comments cannot be +preserved. The command does not need a Git repository and migrating its v7 +output again is idempotent. In v7.0, you can temporarily validate a flat file +with `GITVERSION_CONFIGURATION_VERSION=v6`; GitVersion warns once for that +fallback. + +GitVersion 7 publishes a nested-only schema at +`https://gitversion.net/schemas/7.0/GitVersion.configuration.json`. If you +temporarily select `GITVERSION_CONFIGURATION_VERSION=v6`, keep the existing v6 +`$schema` reference (for example, +`https://gitversion.net/schemas/6.3/GitVersion.configuration.json`) until you +migrate. Do not point a flat document at the 7.0 schema. New v7 configuration +settings require migrating to the nested layout with `gitversion config +migrate` to retain schema validation. + ## Git backend GitVersion v7 introduces a fully managed Git backend as an alternative to the native LibGit2Sharp (libgit2) implementation. The backend is selected with the `GITVERSION_GIT_BACKEND` environment variable. When the variable is not set (or empty), the release's default backend is used — you never need to set it. Setting it to any value other than `libgit2` or `managed` (case-insensitive) is an error: GitVersion fails fast instead of silently running the default backend with a typo unnoticed. @@ -138,7 +166,8 @@ The environment variables relevant to migrating from v6 to v7: | Variable | Purpose | | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------- | -| `GITVERSION_GIT_BACKEND` | Selects the Git backend: `libgit2` (default in v7.0) or `managed`. See [Git backend](#git-backend). | +| `GITVERSION_CONFIGURATION_VERSION` | Selects the configuration layout: `v7` (default) or temporary flat `v6` fallback. | +| `GITVERSION_GIT_BACKEND` | Selects the Git backend: `libgit2` (default in v7.0) or `managed`. See [Git backend](#git-backend). | | `GITVERSION_USE_V6_ARGUMENT_PARSER` | Set to `true` to temporarily restore the legacy v6 (`/switch`) argument parser. Removed in a future release. | | `GITVERSION_REMOTE_USERNAME` | Alternative to `--username` for dynamic-repository credentials. | | `GITVERSION_REMOTE_PASSWORD` | Alternative to `--password` for dynamic-repository credentials. | diff --git a/docs/input/docs/reference/build-servers/gitlab.md b/docs/input/docs/reference/build-servers/gitlab.md index 541efe4e73..578c1221c7 100755 --- a/docs/input/docs/reference/build-servers/gitlab.md +++ b/docs/input/docs/reference/build-servers/gitlab.md @@ -29,11 +29,12 @@ After repository normalisation the friendly branch name becomes GitLab's namespace (the default `pull-requests|pull|pr` pattern does not): ```yaml -workflow: GitFlow/v1 -branches: - pull-request: - regex: ^merge-requests/(?\d+)/(head|merge)$ - label: PullRequest{Number} +calculation: + branches: + pull-request: + label: PullRequest{Number} + regex: ^merge-requests/(?\d+)/(head|merge)$ + workflow: GitFlow/v1 ``` `CI_COMMIT_REF_NAME` still contains the source branch name (for example diff --git a/docs/input/docs/reference/configuration.md b/docs/input/docs/reference/configuration.md index 427ec535b4..ad6ba7771c 100644 --- a/docs/input/docs/reference/configuration.md +++ b/docs/input/docs/reference/configuration.md @@ -21,6 +21,72 @@ found that is generally what is needed when using GitFlow. To see the effective configuration (defaults and overrides), you can run `gitversion --show-config`. +## v7 configuration layout + +GitVersion v7 separates version **calculation** from version **output**. Put +calculation settings under `calculation` and settings that format or publish +the calculated version under `output`: + +```yaml +calculation: + workflow: GitHubFlow/v1 + branches: + main: + increment: Patch +output: + update-build-number: true + branches: + main: + pre-release-weight: 55000 +``` + +`calculation.branches` contains branch-discovery and version-calculation +settings. `output.branches` contains branch-specific output settings. A branch +may appear in either section or both; GitVersion combines both sections into +one effective branch configuration. + +| v6 flat setting | v7 location | +| --- | --- | +| `assembly-file-versioning-format`, `assembly-file-versioning-scheme`, `assembly-informational-format`, `assembly-versioning-format`, `assembly-versioning-scheme`, `commit-date-format`, `custom-version-format`, `pre-release-weight`, `tag-pre-release-weight`, `update-build-number` | `output.` | +| Every other root setting, including `branches`, `ignore`, `next-version`, `strategies`, `tag-prefix`, and `workflow` | `calculation.` | +| Branch `custom-version-format`, `pre-release-weight` | `output.branches..` | +| Every other branch setting, including `increment`, `label`, `mode`, `regex`, and `source-branches` | `calculation.branches..` | + +In v7, `gitversion --show-config` emits this nested structure. The temporary +v6 flat format can be selected only with +`GITVERSION_CONFIGURATION_VERSION=v6` in v7.0; GitVersion warns when it loads +a user configuration that way. + +### Migrating an existing configuration + +Use the POSIX-only migration command to convert a v6 document without opening +a repository: + +```shell +# Discover GitVersion.yml in the target/current directory and write YAML to stdout +gitversion config migrate + +# Select an input explicitly, write a new file, or replace that input +gitversion config migrate --config GitVersion.yml --output GitVersion.v7.yml +gitversion config migrate --config GitVersion.yml --in-place +``` + +`--output` refuses to overwrite an existing file unless `--force` is supplied; +`--output` and `--in-place` cannot be combined. `--in-place` warns because +comments cannot be preserved. The command is deterministic: migrating an +already nested v7 document produces the same YAML again. + +### Overriding v7 configuration + +`--override-config` uses the selected configuration structure. With the v7 +default, use nested keys such as +`--override-config calculation.tag-prefix='[vV]?'` and +`--override-config output.update-build-number=false`. Branch overrides follow +the same ownership map, for example +`calculation.branches.main.increment=Patch` and +`output.branches.main.pre-release-weight=55000`. Flat v6 keys are rejected in +v7 mode with their nested replacement. + ## Global configuration The following supported workflow configurations are available in GitVersion and can be referenced by the workflow property: @@ -494,6 +560,8 @@ expression with `(?-i)`, for example `(?-i)^experimental-`. ### assembly-file-versioning-format +This is an `output` setting: `output.assembly-file-versioning-format`. + Specifies the format of `AssemblyFileVersion` and overwrites the value of `assembly-file-versioning-scheme`. @@ -502,17 +570,22 @@ or a process-scoped environment variable (when prefixed with `env:`). For examp ```yaml # use a variable if non-null or a fallback value otherwise -assembly-file-versioning-format: '{Major}.{Minor}.{Patch}.{WeightedPreReleaseNumber ?? 0}' +output: + assembly-file-versioning-format: '{Major}.{Minor}.{Patch}.{WeightedPreReleaseNumber ?? 0}' # use an environment variable or raise an error if not available -assembly-file-versioning-format: '{Major}.{Minor}.{Patch}.{env:BUILD_NUMBER}' +output: + assembly-file-versioning-format: '{Major}.{Minor}.{Patch}.{env:BUILD_NUMBER}' # use an environment variable if available or a fallback value otherwise -assembly-file-versioning-format: '{Major}.{Minor}.{Patch}.{env:BUILD_NUMBER ?? 42}' +output: + assembly-file-versioning-format: '{Major}.{Minor}.{Patch}.{env:BUILD_NUMBER ?? 42}' ``` ### assembly-file-versioning-scheme +This is an `output` setting: `output.assembly-file-versioning-scheme`. + When updating assembly info, `assembly-file-versioning-scheme` tells GitVersion how to treat the `AssemblyFileVersion` attribute. Note: you can use `None` to skip updating the `AssemblyFileVersion` while still updating the @@ -521,18 +594,24 @@ skip updating the `AssemblyFileVersion` while still updating the ### assembly-informational-format +This is an `output` setting: `output.assembly-informational-format`. + Specifies the format of `AssemblyInformationalVersion`. Follows the same formatting semantics as `assembly-file-versioning-format`. The default value is `{InformationalVersion}`. ### assembly-versioning-format +This is an `output` setting: `output.assembly-versioning-format`. + Specifies the format of `AssemblyVersion` and overwrites the value of `assembly-versioning-scheme`. Follows the same formatting semantics as `assembly-file-versioning-format`. ### assembly-versioning-scheme +This is an `output` setting: `output.assembly-versioning-scheme`. + When updating assembly info, `assembly-versioning-scheme` tells GitVersion how to treat the `AssemblyVersion` attribute. Useful to lock the major when using Strong Naming. Note: you can use `None` to skip updating the `AssemblyVersion` @@ -582,22 +661,26 @@ a named capture group called `Number`. **Example usage:** ```yaml -branches: - pull-request: - mode: ContinuousDelivery - label: PullRequest{Number} - increment: Inherit - prevent-increment: - of-merged-branch: true - when-current-commit-tagged: false - track-merge-message: true - regex: ^(pull-requests|pull|pr)[\/-](?\d*) - source-branches: - - main - - release - - feature - is-source-branch-for: [] - pre-release-weight: 30000 +calculation: + branches: + pull-request: + mode: ContinuousDelivery + label: PullRequest{Number} + increment: Inherit + prevent-increment: + of-merged-branch: true + when-current-commit-tagged: false + track-merge-message: true + regex: ^(pull-requests|pull|pr)[\/-](?\d*) + source-branches: + - main + - release + - feature + is-source-branch-for: [] +output: + branches: + pull-request: + pre-release-weight: 30000 ``` ### mode @@ -606,6 +689,9 @@ Same as for the [global configuration, explained above](#mode). ### pre-release-weight +This is an output setting: `output.pre-release-weight` globally or +`output.branches..pre-release-weight` for a branch. + Provides a way to translate the `PreReleaseLabelName` ([variables][variables]) to a numeric value in order to avoid version collisions across different branches. For example, a release branch created after "1.2.3-alpha.55" results in @@ -658,6 +744,8 @@ Indicates this branch config represents develop in GitFlow. ### commit-date-format +This is an `output` setting: `output.commit-date-format`. + Sets the format which will be used to format the `CommitDate` output variable. ### commit-message-incrementing @@ -668,6 +756,9 @@ details on the syntax. Default set to `Enabled`; set to `Disabled` to disable. ### custom-version-format +This is an `output` setting: `output.custom-version-format` globally or +`output.branches..custom-version-format` for a branch. + 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. `CustomVersion` is empty @@ -695,10 +786,11 @@ semantics, and `^` and `$` can be used to anchor a match. To require case-sensitive matching, prefix a pattern with `(?-i)`. ```yaml -ignore: - branches: - - ^experimental/ - - ^release/legacy$ +calculation: + ignore: + branches: + - ^experimental/ + - ^release/legacy$ ``` The current branch and an explicitly requested target branch remain available @@ -727,9 +819,10 @@ Date and time in the format `yyyy-MM-ddTHH:mm:ss` (eg `commits-before: A sequence of regular expressions that represent paths in the repository. Commits that modify these paths will be excluded from version calculations. For example, to filter out commits that belong to `docs`: ```yaml -ignore: - paths: - - ^docs\/ +calculation: + ignore: + paths: + - ^docs\/ ``` ##### *Monorepo* @@ -740,17 +833,19 @@ As an example, consider a monorepo consisting of subdirectories for `ProjectA`, * Specific match on `/ProjectB/*`: ```yaml -ignore: - paths: - - `^\/ProductB\/.*` +calculation: + ignore: + paths: + - `^\/ProductB\/.*` ``` * Negative lookahead on anything other than `/ProjectA/*` and `/LibraryC/*`: ```yaml -ignore: - paths: - - `^(?!\/ProductA\/|\/LibraryC\/).*` +calculation: + ignore: + paths: + - `^(?!\/ProductA\/|\/LibraryC\/).*` ``` A commit having changes only in `/ProjectB/*` path would be ignored. A commit having changes in the following paths wouldn't be ignored: @@ -779,17 +874,19 @@ there is a rogue commit in history yielding a bad version. You can use either style below: ```yaml -ignore: - sha: [e7bc24c0f34728a25c9187b8d0b041d935763e3a, 764e16321318f2fdb9cdeaa56d1156a1cba307d7] +calculation: + ignore: + sha: [e7bc24c0f34728a25c9187b8d0b041d935763e3a, 764e16321318f2fdb9cdeaa56d1156a1cba307d7] ``` or ```yaml -ignore: - sha: - - e7bc24c0f34728a25c9187b8d0b041d935763e3a - - 764e16321318f2fdb9cdeaa56d1156a1cba307d7 +calculation: + ignore: + sha: + - e7bc24c0f34728a25c9187b8d0b041d935763e3a + - 764e16321318f2fdb9cdeaa56d1156a1cba307d7 ``` #### tags @@ -801,10 +898,11 @@ use OR semantics, and `^` and `$` can be used to anchor a match. To require case-sensitive matching, prefix a pattern with `(?-i)`. ```yaml -ignore: - tags: - - ^experimental- - - ^v0\. +calculation: + ignore: + tags: + - ^experimental- + - ^v0\. ``` Ignoring a tag does not ignore the commit it points to. The commit remains part @@ -838,23 +936,25 @@ branch. A complete example: ```yaml -branches: - unstable: - regex: ... - is-source-branch-for: ['main', 'develop', 'feature', 'hotfix', 'support'] +calculation: + branches: + unstable: + regex: ... + is-source-branch-for: ['main', 'develop', 'feature', 'hotfix', 'support'] ``` Without this configuration value you would have to do: ```yaml -branches: - unstable: - regex: - feature: - source-branches: ['unstable', 'develop', 'feature', 'hotfix', 'support'] - release: - source-branches: ['unstable', 'develop'] - etc... +calculation: + branches: + unstable: + regex: + feature: + source-branches: ['unstable', 'develop', 'feature', 'hotfix', 'support'] + release: + source-branches: ['unstable', 'develop'] + etc... ``` ### major-version-bump-message @@ -1038,7 +1138,12 @@ Configures GitVersion to update the build number or not when running on a build ## Branch configuration -Then we have branch specific configuration, which looks something like this: +The following **v4 migration example** illustrates the change from regular-expression +keys to named branch configurations. It uses the legacy flat layout and is retained +only for that historical migration context; it is not a valid v7 configuration. For +new v7 configuration, place branch calculation settings under `calculation.branches` +and branch output settings under `output.branches`, as shown in the [v7 configuration +layout](#v7-configuration-layout). :::{.alert .alert-info} **Note** @@ -1046,8 +1151,7 @@ Then we have branch specific configuration, which looks something like this: v4 changed from using regexes for keys, to named configs ::: -If you have branch specific configuration upgrading to v4 will force you to -upgrade. +If you have branch-specific configuration, upgrading to v4 required this change. ```yaml workflow: 'GitHubFlow/v1' diff --git a/docs/input/docs/reference/custom-formatting.md b/docs/input/docs/reference/custom-formatting.md index 7ffc2459ab..2367380d89 100644 --- a/docs/input/docs/reference/custom-formatting.md +++ b/docs/input/docs/reference/custom-formatting.md @@ -10,33 +10,36 @@ GitVersion supports C# format strings in configuration, allowing you to apply st 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 -is empty unless a format is configured. Define it at the top level to use one -format for every branch, or override it within a branch configuration when -different deployment modes require different formats. +is empty unless a format is configured. Define it under `output` to use one +format for every branch, or override it within `output.branches` when different +deployment modes require different formats. For example, a PEP 440-compatible pre-release version can omit SemVer's dash and separator: ```yaml -custom-version-format: '{Major}.{Minor}.{Patch}{PreReleaseLabelName:l}{PreReleaseNumber}' -# 0.6.3-beta.10 becomes CustomVersion 0.6.3beta10 +output: + custom-version-format: '{Major}.{Minor}.{Patch}{PreReleaseLabelName:l}{PreReleaseNumber}' + # 0.6.3-beta.10 becomes CustomVersion 0.6.3beta10 ``` For example, a branch-specific format can override the global default: ```yaml -custom-version-format: '{SemVer}' -branches: - feature: - custom-version-format: '{Major}.{Minor}.{Patch}{PreReleaseLabelName:l}{PreReleaseNumber}' +output: + branches: + feature: + custom-version-format: '{Major}.{Minor}.{Patch}{PreReleaseLabelName:l}{PreReleaseNumber}' + custom-version-format: '{SemVer}' ``` 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 +output: + 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 @@ -44,7 +47,8 @@ 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}' +output: + custom-version-format: '{env:ANDROID_VERSION_CODE}' ``` ## Overview @@ -64,7 +68,8 @@ You can now use standard .NET numeric format strings with version components: ```yaml # GitVersion.yml -assembly-informational-format: "{Major}.{Minor}.{Patch:F2}-{PreReleaseLabelName}" +output: + assembly-informational-format: "{Major}.{Minor}.{Patch:F2}-{PreReleaseLabelName}" ``` **Supported Numeric Formats:** @@ -82,7 +87,8 @@ assembly-informational-format: "{Major}.{Minor}.{Patch:F2}-{PreReleaseLabelName} When working with date-related properties like `CommitDate`: ```yaml -assembly-informational-format: "Build-{SemVer}-{CommitDate:yyyy-MM-dd}" +output: + assembly-informational-format: "Build-{SemVer}-{CommitDate:yyyy-MM-dd}" ``` **Common Date Format Specifiers:** @@ -110,19 +116,21 @@ GitVersion introduces custom format specifiers for string case transformations t ```yaml # GitVersion.yml configuration -branches: - feature: - label: "{BranchName:c}" # Converts to PascalCase - -assembly-informational-format: "{Major}.{Minor}.{Patch}-{PreReleaseLabelName:l}.{VersionSourceDistance:0000}" +calculation: + branches: + feature: + label: "{BranchName:c}" # Converts to PascalCase +output: + assembly-informational-format: "{Major}.{Minor}.{Patch}-{PreReleaseLabelName:l}.{VersionSourceDistance:0000}" ``` **Template Usage:** ```yaml # Using format strings in templates -assembly-informational-format: "{Major}.{Minor}.{Patch}-{VersionSourceDistance:0000}" -assembly-informational-format: "{SemVer}-{BranchName:l}" +output: + assembly-informational-format: "{Major}.{Minor}.{Patch}-{VersionSourceDistance:0000}" + assembly-informational-format: "{SemVer}-{BranchName:l}" ``` ## Examples @@ -133,38 +141,42 @@ Based on actual test cases from the implementation: ```yaml # Zero-padded commit count -assembly-informational-format: "{Major}.{Minor}.{Patch}-{VersionSourceDistance:0000}" -# Result: "1.2.3-0042" +output: + assembly-informational-format: "{Major}.{Minor}.{Patch}-{VersionSourceDistance:0000}" + # Result: "1.2.3-0042" ``` ### String Case Transformations ```yaml -branches: - feature: - label: "{BranchName:c}" # PascalCase: "feature-branch" → "FeatureBranch" - hotfix: - label: "hotfix-{BranchName:l}" # Lowercase: "HOTFIX-BRANCH" → "hotfix-branch" +calculation: + branches: + feature: + label: "{BranchName:c}" # PascalCase: "feature-branch" → "FeatureBranch" + hotfix: + label: "hotfix-{BranchName:l}" # Lowercase: "HOTFIX-BRANCH" → "hotfix-branch" ``` ### Date and Time Formatting ```yaml -assembly-informational-format: "{SemVer}-build-{CommitDate:yyyy-MM-dd}" -# Result: "1.2.3-build-2021-01-01" +output: + assembly-informational-format: "{SemVer}-build-{CommitDate:yyyy-MM-dd}" + # Result: "1.2.3-build-2021-01-01" ``` ### Numeric Formatting ```yaml -# Currency format (uses InvariantCulture) -assembly-informational-format: "Cost-{Major:C}" # Result: "Cost-¤1.00" +output: + # Currency format (uses InvariantCulture) + assembly-informational-format: "Cost-{Major:C}" # Result: "Cost-¤1.00" -# Percentage format -assembly-informational-format: "Progress-{Minor:P}" # Result: "Progress-200.00 %" + # Percentage format + assembly-informational-format: "Progress-{Minor:P}" # Result: "Progress-200.00 %" -# Thousands separator -assembly-informational-format: "Build-{VersionSourceDistance:N0}" # Result: "Build-1,234" + # Thousands separator + assembly-informational-format: "Build-{VersionSourceDistance:N0}" # Result: "Build-1,234" ``` ## Configuration Integration @@ -175,17 +187,19 @@ The format strings are used in GitVersion configuration files through various fo ```yaml # GitVersion.yml -assembly-informational-format: "{Major}.{Minor}.{Patch}-{VersionSourceDistance:0000}" -assembly-versioning-format: "{Major}.{Minor}.{Patch}.{env:BUILD_NUMBER}" -assembly-file-versioning-format: "{MajorMinorPatch}.{VersionSourceDistance}" +output: + assembly-file-versioning-format: "{MajorMinorPatch}.{VersionSourceDistance}" + assembly-informational-format: "{Major}.{Minor}.{Patch}-{VersionSourceDistance:0000}" + assembly-versioning-format: "{Major}.{Minor}.{Patch}.{env:BUILD_NUMBER}" ``` ### Environment Variable Integration ```yaml # Using environment variables with fallbacks -assembly-informational-format: "{Major}.{Minor}.{Patch}-{env:RELEASE_STAGE ?? 'dev'}" -assembly-informational-format: "{SemVer}+{env:BUILD_ID ?? 'local'}" +output: + assembly-informational-format: "{Major}.{Minor}.{Patch}-{env:RELEASE_STAGE ?? 'dev'}" + assembly-informational-format: "{SemVer}+{env:BUILD_ID ?? 'local'}" ``` ### Real-World Integration Examples @@ -193,16 +207,18 @@ assembly-informational-format: "{SemVer}+{env:BUILD_ID ?? 'local'}" Based on the actual test implementation: ```yaml -# Example from VariableProviderTests.cs -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.{VersionSourceDistance:00}" +calculation: + # Branch-specific formatting + branches: + feature: + label: "{BranchName:c}" # PascalCase conversion + hotfix: + label: "hotfix.{VersionSourceDistance:00}" + +output: + # Example from VariableProviderTests.cs + assembly-informational-format: "{Major}.{Minor}.{Patch}-{VersionSourceDistance:0000}" + # Result: "1.2.3-0042" when VersionSourceDistance = 42 ``` ## Invariant Culture Formatting diff --git a/docs/input/docs/reference/mdsource/configuration.source.md b/docs/input/docs/reference/mdsource/configuration.source.md index 18d6fe52b9..d736fcf735 100644 --- a/docs/input/docs/reference/mdsource/configuration.source.md +++ b/docs/input/docs/reference/mdsource/configuration.source.md @@ -21,6 +21,72 @@ found that is generally what is needed when using GitFlow. To see the effective configuration (defaults and overrides), you can run `gitversion --show-config`. +## v7 configuration layout + +GitVersion v7 separates version **calculation** from version **output**. Put +calculation settings under `calculation` and settings that format or publish +the calculated version under `output`: + +```yaml +calculation: + workflow: GitHubFlow/v1 + branches: + main: + increment: Patch +output: + update-build-number: true + branches: + main: + pre-release-weight: 55000 +``` + +`calculation.branches` contains branch-discovery and version-calculation +settings. `output.branches` contains branch-specific output settings. A branch +may appear in either section or both; GitVersion combines both sections into +one effective branch configuration. + +| v6 flat setting | v7 location | +| --- | --- | +| `assembly-file-versioning-format`, `assembly-file-versioning-scheme`, `assembly-informational-format`, `assembly-versioning-format`, `assembly-versioning-scheme`, `commit-date-format`, `custom-version-format`, `pre-release-weight`, `tag-pre-release-weight`, `update-build-number` | `output.` | +| Every other root setting, including `branches`, `ignore`, `next-version`, `strategies`, `tag-prefix`, and `workflow` | `calculation.` | +| Branch `custom-version-format`, `pre-release-weight` | `output.branches..` | +| Every other branch setting, including `increment`, `label`, `mode`, `regex`, and `source-branches` | `calculation.branches..` | + +In v7, `gitversion --show-config` emits this nested structure. The temporary +v6 flat format can be selected only with +`GITVERSION_CONFIGURATION_VERSION=v6` in v7.0; GitVersion warns when it loads +a user configuration that way. + +### Migrating an existing configuration + +Use the POSIX-only migration command to convert a v6 document without opening +a repository: + +```shell +# Discover GitVersion.yml in the target/current directory and write YAML to stdout +gitversion config migrate + +# Select an input explicitly, write a new file, or replace that input +gitversion config migrate --config GitVersion.yml --output GitVersion.v7.yml +gitversion config migrate --config GitVersion.yml --in-place +``` + +`--output` refuses to overwrite an existing file unless `--force` is supplied; +`--output` and `--in-place` cannot be combined. `--in-place` warns because +comments cannot be preserved. The command is deterministic: migrating an +already nested v7 document produces the same YAML again. + +### Overriding v7 configuration + +`--override-config` uses the selected configuration structure. With the v7 +default, use nested keys such as +`--override-config calculation.tag-prefix='[vV]?'` and +`--override-config output.update-build-number=false`. Branch overrides follow +the same ownership map, for example +`calculation.branches.main.increment=Patch` and +`output.branches.main.pre-release-weight=55000`. Flat v6 keys are rejected in +v7 mode with their nested replacement. + ## Global configuration The following supported workflow configurations are available in GitVersion and can be referenced by the workflow property: @@ -61,6 +127,8 @@ expression with `(?-i)`, for example `(?-i)^experimental-`. ### assembly-file-versioning-format +This is an `output` setting: `output.assembly-file-versioning-format`. + Specifies the format of `AssemblyFileVersion` and overwrites the value of `assembly-file-versioning-scheme`. @@ -69,17 +137,22 @@ or a process-scoped environment variable (when prefixed with `env:`). For examp ```yaml # use a variable if non-null or a fallback value otherwise -assembly-file-versioning-format: '{Major}.{Minor}.{Patch}.{WeightedPreReleaseNumber ?? 0}' +output: + assembly-file-versioning-format: '{Major}.{Minor}.{Patch}.{WeightedPreReleaseNumber ?? 0}' # use an environment variable or raise an error if not available -assembly-file-versioning-format: '{Major}.{Minor}.{Patch}.{env:BUILD_NUMBER}' +output: + assembly-file-versioning-format: '{Major}.{Minor}.{Patch}.{env:BUILD_NUMBER}' # use an environment variable if available or a fallback value otherwise -assembly-file-versioning-format: '{Major}.{Minor}.{Patch}.{env:BUILD_NUMBER ?? 42}' +output: + assembly-file-versioning-format: '{Major}.{Minor}.{Patch}.{env:BUILD_NUMBER ?? 42}' ``` ### assembly-file-versioning-scheme +This is an `output` setting: `output.assembly-file-versioning-scheme`. + When updating assembly info, `assembly-file-versioning-scheme` tells GitVersion how to treat the `AssemblyFileVersion` attribute. Note: you can use `None` to skip updating the `AssemblyFileVersion` while still updating the @@ -88,18 +161,24 @@ skip updating the `AssemblyFileVersion` while still updating the ### assembly-informational-format +This is an `output` setting: `output.assembly-informational-format`. + Specifies the format of `AssemblyInformationalVersion`. Follows the same formatting semantics as `assembly-file-versioning-format`. The default value is `{InformationalVersion}`. ### assembly-versioning-format +This is an `output` setting: `output.assembly-versioning-format`. + Specifies the format of `AssemblyVersion` and overwrites the value of `assembly-versioning-scheme`. Follows the same formatting semantics as `assembly-file-versioning-format`. ### assembly-versioning-scheme +This is an `output` setting: `output.assembly-versioning-scheme`. + When updating assembly info, `assembly-versioning-scheme` tells GitVersion how to treat the `AssemblyVersion` attribute. Useful to lock the major when using Strong Naming. Note: you can use `None` to skip updating the `AssemblyVersion` @@ -149,22 +228,26 @@ a named capture group called `Number`. **Example usage:** ```yaml -branches: - pull-request: - mode: ContinuousDelivery - label: PullRequest{Number} - increment: Inherit - prevent-increment: - of-merged-branch: true - when-current-commit-tagged: false - track-merge-message: true - regex: ^(pull-requests|pull|pr)[\/-](?\d*) - source-branches: - - main - - release - - feature - is-source-branch-for: [] - pre-release-weight: 30000 +calculation: + branches: + pull-request: + mode: ContinuousDelivery + label: PullRequest{Number} + increment: Inherit + prevent-increment: + of-merged-branch: true + when-current-commit-tagged: false + track-merge-message: true + regex: ^(pull-requests|pull|pr)[\/-](?\d*) + source-branches: + - main + - release + - feature + is-source-branch-for: [] +output: + branches: + pull-request: + pre-release-weight: 30000 ``` ### mode @@ -173,6 +256,9 @@ Same as for the [global configuration, explained above](#mode). ### pre-release-weight +This is an output setting: `output.pre-release-weight` globally or +`output.branches..pre-release-weight` for a branch. + Provides a way to translate the `PreReleaseLabelName` ([variables][variables]) to a numeric value in order to avoid version collisions across different branches. For example, a release branch created after "1.2.3-alpha.55" results in @@ -225,6 +311,8 @@ Indicates this branch config represents develop in GitFlow. ### commit-date-format +This is an `output` setting: `output.commit-date-format`. + Sets the format which will be used to format the `CommitDate` output variable. ### commit-message-incrementing @@ -235,6 +323,9 @@ details on the syntax. Default set to `Enabled`; set to `Disabled` to disable. ### custom-version-format +This is an `output` setting: `output.custom-version-format` globally or +`output.branches..custom-version-format` for a branch. + 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. `CustomVersion` is empty @@ -262,10 +353,11 @@ semantics, and `^` and `$` can be used to anchor a match. To require case-sensitive matching, prefix a pattern with `(?-i)`. ```yaml -ignore: - branches: - - ^experimental/ - - ^release/legacy$ +calculation: + ignore: + branches: + - ^experimental/ + - ^release/legacy$ ``` The current branch and an explicitly requested target branch remain available @@ -294,9 +386,10 @@ Date and time in the format `yyyy-MM-ddTHH:mm:ss` (eg `commits-before: A sequence of regular expressions that represent paths in the repository. Commits that modify these paths will be excluded from version calculations. For example, to filter out commits that belong to `docs`: ```yaml -ignore: - paths: - - ^docs\/ +calculation: + ignore: + paths: + - ^docs\/ ``` ##### *Monorepo* @@ -307,17 +400,19 @@ As an example, consider a monorepo consisting of subdirectories for `ProjectA`, * Specific match on `/ProjectB/*`: ```yaml -ignore: - paths: - - `^\/ProductB\/.*` +calculation: + ignore: + paths: + - `^\/ProductB\/.*` ``` * Negative lookahead on anything other than `/ProjectA/*` and `/LibraryC/*`: ```yaml -ignore: - paths: - - `^(?!\/ProductA\/|\/LibraryC\/).*` +calculation: + ignore: + paths: + - `^(?!\/ProductA\/|\/LibraryC\/).*` ``` A commit having changes only in `/ProjectB/*` path would be ignored. A commit having changes in the following paths wouldn't be ignored: @@ -346,17 +441,19 @@ there is a rogue commit in history yielding a bad version. You can use either style below: ```yaml -ignore: - sha: [e7bc24c0f34728a25c9187b8d0b041d935763e3a, 764e16321318f2fdb9cdeaa56d1156a1cba307d7] +calculation: + ignore: + sha: [e7bc24c0f34728a25c9187b8d0b041d935763e3a, 764e16321318f2fdb9cdeaa56d1156a1cba307d7] ``` or ```yaml -ignore: - sha: - - e7bc24c0f34728a25c9187b8d0b041d935763e3a - - 764e16321318f2fdb9cdeaa56d1156a1cba307d7 +calculation: + ignore: + sha: + - e7bc24c0f34728a25c9187b8d0b041d935763e3a + - 764e16321318f2fdb9cdeaa56d1156a1cba307d7 ``` #### tags @@ -368,10 +465,11 @@ use OR semantics, and `^` and `$` can be used to anchor a match. To require case-sensitive matching, prefix a pattern with `(?-i)`. ```yaml -ignore: - tags: - - ^experimental- - - ^v0\. +calculation: + ignore: + tags: + - ^experimental- + - ^v0\. ``` Ignoring a tag does not ignore the commit it points to. The commit remains part @@ -405,23 +503,25 @@ branch. A complete example: ```yaml -branches: - unstable: - regex: ... - is-source-branch-for: ['main', 'develop', 'feature', 'hotfix', 'support'] +calculation: + branches: + unstable: + regex: ... + is-source-branch-for: ['main', 'develop', 'feature', 'hotfix', 'support'] ``` Without this configuration value you would have to do: ```yaml -branches: - unstable: - regex: - feature: - source-branches: ['unstable', 'develop', 'feature', 'hotfix', 'support'] - release: - source-branches: ['unstable', 'develop'] - etc... +calculation: + branches: + unstable: + regex: + feature: + source-branches: ['unstable', 'develop', 'feature', 'hotfix', 'support'] + release: + source-branches: ['unstable', 'develop'] + etc... ``` ### major-version-bump-message @@ -605,7 +705,12 @@ Configures GitVersion to update the build number or not when running on a build ## Branch configuration -Then we have branch specific configuration, which looks something like this: +The following **v4 migration example** illustrates the change from regular-expression +keys to named branch configurations. It uses the legacy flat layout and is retained +only for that historical migration context; it is not a valid v7 configuration. For +new v7 configuration, place branch calculation settings under `calculation.branches` +and branch output settings under `output.branches`, as shown in the [v7 configuration +layout](#v7-configuration-layout). :::{.alert .alert-info} **Note** @@ -613,8 +718,7 @@ Then we have branch specific configuration, which looks something like this: v4 changed from using regexes for keys, to named configs ::: -If you have branch specific configuration upgrading to v4 will force you to -upgrade. +If you have branch-specific configuration, upgrading to v4 required this change. ```yaml workflow: 'GitHubFlow/v1' diff --git a/docs/input/docs/reference/version-increments.md b/docs/input/docs/reference/version-increments.md index 6cbb76186e..60c1e03a90 100644 --- a/docs/input/docs/reference/version-increments.md +++ b/docs/input/docs/reference/version-increments.md @@ -78,12 +78,13 @@ The feature is enabled by default but can be disabled via configuration, the regex we use can be changed: ```yaml -major-version-bump-message: '[+=]semver:\s?(breaking|major)' -minor-version-bump-message: '[+=]semver:\s?(feature|minor)' -patch-version-bump-message: '[+=]semver:\s?(fix|patch)' -no-bump-message: '[+=]semver:\s?(none|skip)' -version-bump-reset-message: '=semver:' -commit-message-incrementing: Enabled +calculation: + commit-message-incrementing: Enabled + major-version-bump-message: '[+=]semver:\s?(breaking|major)' + minor-version-bump-message: '[+=]semver:\s?(feature|minor)' + no-bump-message: '[+=]semver:\s?(none|skip)' + patch-version-bump-message: '[+=]semver:\s?(fix|patch)' + version-bump-reset-message: '=semver:' ``` The options for `commit-message-incrementing` are `Enabled`, `MergeMessageOnly` @@ -99,10 +100,11 @@ If you want to use the [Conventional Commits][conventional-commits] standard, you can leverage this feature as follows: ```yaml -mode: MainLine # Only add this if you want every version to be created automatically on your main branch. -major-version-bump-message: "^(build|chore|ci|docs|feat|fix|perf|refactor|revert|style|test)(\\([\\w\\s-,/\\\\]*\\))?(!:|:.*\\n\\n((.+\\n)+\\n)?BREAKING CHANGE:\\s.+)" -minor-version-bump-message: "^(feat)(\\([\\w\\s-,/\\\\]*\\))?:" -patch-version-bump-message: "^(fix|perf)(\\([\\w\\s-,/\\\\]*\\))?:" +calculation: + major-version-bump-message: "^(build|chore|ci|docs|feat|fix|perf|refactor|revert|style|test)(\\([\\w\\s-,/\\\\]*\\))?(!:|:.*\\n\\n((.+\\n)+\\n)?BREAKING CHANGE:\\s.+)" + minor-version-bump-message: "^(feat)(\\([\\w\\s-,/\\\\]*\\))?:" + mode: MainLine # Only add this if you want every version to be created automatically on your main branch. + patch-version-bump-message: "^(fix|perf)(\\([\\w\\s-,/\\\\]*\\))?:" ``` This will ensure that your version gets bumped according to the commits you've diff --git a/docs/input/docs/usage/cli/arguments.md b/docs/input/docs/usage/cli/arguments.md index f837afd55e..0f326f44c3 100644 --- a/docs/input/docs/usage/cli/arguments.md +++ b/docs/input/docs/usage/cli/arguments.md @@ -107,10 +107,39 @@ GitVersion [path] GitVersion to not calculate your version as expected. ``` +## Configuration migration + +The POSIX parser exposes a `config migrate` subcommand for converting a v6 +configuration document to the v7 `calculation`/`output` layout: + +```shell +gitversion config migrate +gitversion config migrate --config GitVersion.yml --output GitVersion.v7.yml +gitversion config migrate --config GitVersion.yml --in-place +``` + +It discovers a supported configuration filename when `--config` is omitted and +writes YAML to stdout unless `--output` or `--in-place` is selected. `--output` +will not replace an existing file without `--force`; it cannot be combined with +`--in-place`. Replacing a file warns that comments are not preserved. The +command does not require a Git repository and is unavailable when +`GITVERSION_USE_V6_ARGUMENT_PARSER=true` selects the legacy parser. + ## Override config `--override-config key=value` will override appropriate `key` from 'GitVersion.yml', 'GitVersion.yaml', '.GitVersion.yml' or '.GitVersion.yaml'. +With the v7 default configuration layout, use a version-aware nested key. For +example, `calculation.tag-prefix=custom`, +`calculation.branches.main.increment=Patch`, and +`output.branches.main.pre-release-weight=55000`. Flat v6 keys are rejected in +v7 mode with their nested replacement. Set +`GITVERSION_CONFIGURATION_VERSION=v6` only while validating a legacy file in +v7.0. + +When that temporary v6 fallback is selected, use the legacy branch override +path, for example `--override-config branches.main.increment=Patch`. + To specify multiple options add multiple `--override-config key=value` entries: `--override-config key1=value1 --override-config key2=value2`. @@ -147,28 +176,28 @@ Using `override-config` on the command line will not change the contents of the ### Example: How to override configuration option 'tag-prefix' to use prefix 'custom' -`GitVersion.exe --output json --override-config tag-prefix=custom` +`GitVersion.exe --output json --override-config calculation.tag-prefix=custom` ### Example: How to override configuration option 'assembly-versioning-format' -`GitVersion.exe --output json --override-config assembly-versioning-format="{Major}.{Minor}.{Patch}.{env:BUILD_NUMBER ?? 0}"` +`GitVersion.exe --output json --override-config output.assembly-versioning-format="{Major}.{Minor}.{Patch}.{env:BUILD_NUMBER ?? 0}"` Will pickup up environment variable `BUILD_NUMBER` or fallback to zero for assembly revision number. ### Example: How to override configuration option 'assembly-versioning-scheme' -`GitVersion.exe --output json --override-config assembly-versioning-scheme=MajorMinor` +`GitVersion.exe --output json --override-config output.assembly-versioning-scheme=MajorMinor` Will use only major and minor version numbers for assembly version. Assembly build and revision numbers will be 0 (e.g. `1.2.0.0`) ### Example: How to override multiple configuration options -`GitVersion.exe --output json --override-config tag-prefix=custom --override-config assembly-versioning-scheme=MajorMinor` +`GitVersion.exe --output json --override-config calculation.tag-prefix=custom --override-config output.assembly-versioning-scheme=MajorMinor` ### Example: How to override configuration option 'update-build-number' -`GitVersion.exe --output json --override-config update-build-number=true` +`GitVersion.exe --output json --override-config output.update-build-number=true` ### Example: How to override configuration option 'next-version' -`GitVersion.exe --output json --override-config next-version=6` +`GitVersion.exe --output json --override-config calculation.next-version=6` diff --git a/docs/input/docs/usage/cli/assembly-patch.md b/docs/input/docs/usage/cli/assembly-patch.md index f8ec0ee58c..a256dc04a6 100644 --- a/docs/input/docs/usage/cli/assembly-patch.md +++ b/docs/input/docs/usage/cli/assembly-patch.md @@ -71,7 +71,7 @@ Will iterate through each file and update known attributes (`AssemblyVersion`, ## Example: How to override configuration option 'tag-prefix' to use prefix 'custom' -`GitVersion.exe --output json --override-config tag-prefix=custom` +`GitVersion.exe --output json --override-config calculation.tag-prefix=custom` ## Writing version metadata in WiX format