From 778098d5905b354b2a2ee5f54946c44add2653fb Mon Sep 17 00:00:00 2001 From: Artur Stolear Date: Wed, 19 Aug 2026 23:15:32 +0200 Subject: [PATCH] docs: document v7 configuration migration --- BREAKING_CHANGES.md | 20 ++ .../branching-strategies/gitflow/examples.md | 3 +- .../githubflow/examples.md | 3 +- docs/input/docs/migration/v6-to-v7.md | 33 ++- .../docs/reference/build-servers/gitlab.md | 9 +- docs/input/docs/reference/configuration.md | 252 +++++++++++++----- .../input/docs/reference/custom-formatting.md | 120 +++++---- .../mdsource/configuration.source.md | 252 +++++++++++++----- .../docs/reference/version-increments.md | 22 +- docs/input/docs/usage/cli/arguments.md | 105 +++++--- docs/input/docs/usage/cli/assembly-patch.md | 2 +- 11 files changed, 581 insertions(+), 240 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..a45f541832 100644 --- a/docs/input/docs/learn/branching-strategies/gitflow/examples.md +++ b/docs/input/docs/learn/branching-strategies/gitflow/examples.md @@ -13,7 +13,8 @@ configuration as follows: ```yaml workflow: GitFlow/v1 -mode: ContinuousDelivery +calculation: + mode: ContinuousDelivery ``` 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..b482026bb5 100644 --- a/docs/input/docs/learn/branching-strategies/githubflow/examples.md +++ b/docs/input/docs/learn/branching-strategies/githubflow/examples.md @@ -11,7 +11,8 @@ configuration as follows: ```yaml workflow: GitHubFlow/v1 -mode: ContinuousDelivery +calculation: + mode: ContinuousDelivery ``` Where diff --git a/docs/input/docs/migration/v6-to-v7.md b/docs/input/docs/migration/v6-to-v7.md index 6fa12f2eb2..3cb7e924f6 100644 --- a/docs/input/docs/migration/v6-to-v7.md +++ b/docs/input/docs/migration/v6-to-v7.md @@ -117,6 +117,36 @@ 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 migration command using the default +POSIX-style argument parser. This works on all supported operating systems; +the legacy v6 argument parser does not support the 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 +168,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..7be73bc32e 100755 --- a/docs/input/docs/reference/build-servers/gitlab.md +++ b/docs/input/docs/reference/build-servers/gitlab.md @@ -30,10 +30,11 @@ 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)$ ``` `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 7265143f16..bdfe0bfe68 100644 --- a/docs/input/docs/reference/configuration.md +++ b/docs/input/docs/reference/configuration.md @@ -21,6 +21,86 @@ 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 +workflow: GitHubFlow/v1 +calculation: + 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. + +`workflow` belongs at the document root because it selects a preset for the +whole configuration. Presets can supply defaults for both `calculation` and +`output`, including output settings for branches defined by the preset. User +configuration overrides those defaults, and runtime overrides take precedence +over the user configuration. A file containing only `workflow: GitHubFlow/v1` +is valid in either configuration format. + +| 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.` | +| `workflow` | `workflow` (unchanged, applies to both sections) | +| Every other root setting, including `branches`, `ignore`, `next-version`, `strategies`, and `tag-prefix` | `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 migration command with the default POSIX-style argument parser to +convert a v6 document without opening a repository. It works on all supported +operating systems; the legacy v6 argument parser does not support it: + +```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. + +Migration also relocates `calculation.workflow` from the earlier v7 draft layout +to the root. Runtime loading accepts only root-level `workflow`; duplicate +root/nested selectors and `output.workflow` are rejected. + +### Overriding v7 configuration + +`--override-config` uses the selected configuration structure. With the v7 +default, use root-level `--override-config workflow=GitHubFlow/v1` for the preset, +and 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 +574,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 +584,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 +608,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 +675,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 +703,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 +758,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 +770,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 +800,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,40 +833,43 @@ 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* This ignore config can be used to filter only those commits that belong to a specific project in a monorepo. -As an example, consider a monorepo consisting of subdirectories for `ProjectA`, `ProjectB` and a shared `LibraryC`. For GitVersion to consider only commits that are part of `projectA` and shared library `LibraryC`, a regex that matches all paths except those starting with `ProjectA` or `LibraryC` can be used. Either one of the following configs would filter out `ProjectB`. +As an example, consider a monorepo consisting of subdirectories for `ProjectA`, `ProjectB` and a shared `LibraryC`. For GitVersion to consider only commits that are part of `ProjectA` and shared library `LibraryC`, a regex that matches all paths except those starting with `ProjectA` or `LibraryC` can be used. Either one of the following configs would filter out `ProjectB`. -* Specific match on `/ProjectB/*`: +* Specific match on `ProjectB/*`: ```yaml -ignore: - paths: - - `^\/ProductB\/.*` +calculation: + ignore: + paths: + - '^ProjectB/.*' ``` -* Negative lookahead on anything other than `/ProjectA/*` and `/LibraryC/*`: +* Negative lookahead on anything other than `ProjectA/*` and `LibraryC/*`: ```yaml -ignore: - paths: - - `^(?!\/ProductA\/|\/LibraryC\/).*` +calculation: + ignore: + paths: + - '^(?!ProjectA/|LibraryC/).*' ``` -A commit having changes only in `/ProjectB/*` path would be ignored. A commit having changes in the following paths wouldn't be ignored: +A commit having changes only in `ProjectB/*` path would be ignored. A commit having changes in the following paths wouldn't be ignored: -* `/ProductA/*` -* `/LibraryC/*` -* `/ProductA/*` and `/LibraryC/*` -* `/ProductA/*` and `/ProductB/*` -* `/LibraryC/*` and `/ProductB/*` -* `/ProductA/*` and `/ProductB/*` and `/LibraryC/*` +* `ProjectA/*` +* `LibraryC/*` +* `ProjectA/*` and `LibraryC/*` +* `ProjectA/*` and `ProjectB/*` +* `LibraryC/*` and `ProjectB/*` +* `ProjectA/*` and `ProjectB/*` and `LibraryC/*` ::: Note: The `ignore.paths` configuration is case-insensitive. To require @@ -779,17 +888,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 +912,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 +950,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 +1152,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 +1165,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..a26c7e1be4 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,22 @@ 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}" + # Alternative: + # assembly-informational-format: "{SemVer}-{BranchName:l}" ``` ## Examples @@ -133,38 +142,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 %" + # Alternative: percentage format + # assembly-informational-format: "Progress-{Minor:P}" # Result: "Progress-200.00 %" -# Thousands separator -assembly-informational-format: "Build-{VersionSourceDistance:N0}" # Result: "Build-1,234" + # Alternative: thousands separator + # assembly-informational-format: "Build-{VersionSourceDistance:N0}" # Result: "Build-1,234" ``` ## Configuration Integration @@ -175,17 +188,20 @@ 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'}" + # Alternative: + # assembly-informational-format: "{SemVer}+{env:BUILD_ID ?? 'local'}" ``` ### Real-World Integration Examples @@ -193,16 +209,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 9fb8f0330d..ed5eed1ec7 100644 --- a/docs/input/docs/reference/mdsource/configuration.source.md +++ b/docs/input/docs/reference/mdsource/configuration.source.md @@ -21,6 +21,86 @@ 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 +workflow: GitHubFlow/v1 +calculation: + 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. + +`workflow` belongs at the document root because it selects a preset for the +whole configuration. Presets can supply defaults for both `calculation` and +`output`, including output settings for branches defined by the preset. User +configuration overrides those defaults, and runtime overrides take precedence +over the user configuration. A file containing only `workflow: GitHubFlow/v1` +is valid in either configuration format. + +| 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.` | +| `workflow` | `workflow` (unchanged, applies to both sections) | +| Every other root setting, including `branches`, `ignore`, `next-version`, `strategies`, and `tag-prefix` | `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 migration command with the default POSIX-style argument parser to +convert a v6 document without opening a repository. It works on all supported +operating systems; the legacy v6 argument parser does not support it: + +```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. + +Migration also relocates `calculation.workflow` from the earlier v7 draft layout +to the root. Runtime loading accepts only root-level `workflow`; duplicate +root/nested selectors and `output.workflow` are rejected. + +### Overriding v7 configuration + +`--override-config` uses the selected configuration structure. With the v7 +default, use root-level `--override-config workflow=GitHubFlow/v1` for the preset, +and 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 +141,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 +151,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 +175,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 +242,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 +270,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 +325,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 +337,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 +367,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,40 +400,43 @@ 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* This ignore config can be used to filter only those commits that belong to a specific project in a monorepo. -As an example, consider a monorepo consisting of subdirectories for `ProjectA`, `ProjectB` and a shared `LibraryC`. For GitVersion to consider only commits that are part of `projectA` and shared library `LibraryC`, a regex that matches all paths except those starting with `ProjectA` or `LibraryC` can be used. Either one of the following configs would filter out `ProjectB`. +As an example, consider a monorepo consisting of subdirectories for `ProjectA`, `ProjectB` and a shared `LibraryC`. For GitVersion to consider only commits that are part of `ProjectA` and shared library `LibraryC`, a regex that matches all paths except those starting with `ProjectA` or `LibraryC` can be used. Either one of the following configs would filter out `ProjectB`. -* Specific match on `/ProjectB/*`: +* Specific match on `ProjectB/*`: ```yaml -ignore: - paths: - - `^\/ProductB\/.*` +calculation: + ignore: + paths: + - '^ProjectB/.*' ``` -* Negative lookahead on anything other than `/ProjectA/*` and `/LibraryC/*`: +* Negative lookahead on anything other than `ProjectA/*` and `LibraryC/*`: ```yaml -ignore: - paths: - - `^(?!\/ProductA\/|\/LibraryC\/).*` +calculation: + ignore: + paths: + - '^(?!ProjectA/|LibraryC/).*' ``` -A commit having changes only in `/ProjectB/*` path would be ignored. A commit having changes in the following paths wouldn't be ignored: +A commit having changes only in `ProjectB/*` path would be ignored. A commit having changes in the following paths wouldn't be ignored: -* `/ProductA/*` -* `/LibraryC/*` -* `/ProductA/*` and `/LibraryC/*` -* `/ProductA/*` and `/ProductB/*` -* `/LibraryC/*` and `/ProductB/*` -* `/ProductA/*` and `/ProductB/*` and `/LibraryC/*` +* `ProjectA/*` +* `LibraryC/*` +* `ProjectA/*` and `LibraryC/*` +* `ProjectA/*` and `ProjectB/*` +* `LibraryC/*` and `ProjectB/*` +* `ProjectA/*` and `ProjectB/*` and `LibraryC/*` ::: Note: The `ignore.paths` configuration is case-insensitive. To require @@ -346,17 +455,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 +479,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 +517,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 +719,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 +732,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..0a8e58faac 100644 --- a/docs/input/docs/usage/cli/arguments.md +++ b/docs/input/docs/usage/cli/arguments.md @@ -52,10 +52,9 @@ GitVersion [path] --show-config Outputs the effective GitVersion config (defaults + custom from GitVersion.yml, GitVersion.yaml, .GitVersion.yml or .GitVersion.yaml) in yaml format --override-config - Overrides GitVersion config values inline (semicolon- - separated key value pairs e.g. --override-config - tag-prefix=Foo) - Currently supported config overrides: tag-prefix + Overrides GitVersion config values inline (key=value pairs, + e.g. --override-config workflow=GitHubFlow/v1). + Repeat --override-config for multiple overrides. --no-cache Bypasses the cache, result will not be written to the cache. --no-normalize Disables normalize step on a build server. --allow-shallow Allows GitVersion to run on a shallow clone. @@ -107,39 +106,71 @@ GitVersion [path] GitVersion to not calculate your version as expected. ``` +## Configuration migration + +The default POSIX-style argument 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`. -To have **space characters** as a part of `value`, `value` has be enclosed with double quotes - `key="My value"`. - -Double quote character inside of the double quoted `value` has to be be escaped with a backslash '\\' - `key="My \"escaped-quotes\""`. - -Following options are supported: - -1. `assembly-file-versioning-format` -2. `assembly-file-versioning-scheme` -3. `assembly-informational-format` -4. `assembly-versioning-format` -5. `assembly-versioning-scheme` -6. `commit-date-format` -7. `commit-message-incrementing` -8. `custom-version-format` -9. `label` -10. `increment` -11. `major-version-bump-message` -12. `minor-version-bump-message` -13. `mode` -14. `next-version` -15. `no-bump-message` -16. `patch-version-bump-message` -17. `tag-prefix` -18. `tag-pre-release-weight` -19. `update-build-number` -20. `version-bump-reset-message` +To have **space characters** as a part of `value`, `value` has to be enclosed with double quotes - `key="My value"`. + +Double quote character inside of the double quoted `value` has to be escaped with a backslash '\\' - `key="My \"escaped-quotes\""`. + +The following override paths are supported in v7. For the temporary v6 +fallback, omit the `calculation.` or `output.` prefix. The shared `workflow` +key stays at the root in both versions: + +1. `output.assembly-file-versioning-format` +2. `output.assembly-file-versioning-scheme` +3. `output.assembly-informational-format` +4. `output.assembly-versioning-format` +5. `output.assembly-versioning-scheme` +6. `output.commit-date-format` +7. `calculation.commit-message-incrementing` +8. `output.custom-version-format` +9. `calculation.label` +10. `calculation.increment` +11. `calculation.major-version-bump-message` +12. `calculation.minor-version-bump-message` +13. `calculation.mode` +14. `calculation.next-version` +15. `calculation.no-bump-message` +16. `calculation.patch-version-bump-message` +17. `calculation.tag-prefix` +18. `output.tag-pre-release-weight` +19. `output.update-build-number` +20. `calculation.version-bump-reset-message` +21. `workflow` Read more about [Configuration](/docs/reference/configuration). @@ -147,28 +178,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. +Uses the environment variable `BUILD_NUMBER`, or falls back to zero for the 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