Order | Title | Description | RedirectFrom |
---|---|---|---|
10 |
Configuration |
Details about how GitVersion can be configured to suit your needs |
docs/configuration |
GitVersion, starting from version 3.0, is mainly powered by configuration and no longer has branching strategies hard-coded.
If you run gitversion init
, GitVersion will launch into a configuration tool,
which can help you configure GitVersion the way you want it.
Once complete, the init
command will create a GitVersion.yml
file in the
working directory. It can be the root repository directory or any subdirectory
in case you have a single repository for more than one project or are restricted
to commit into a subdirectory.
:::{.alert .alert-info} Note
GitVersion ships with internal default configuration which works with GitHubFlow and GitFlow, probably with others too. :::
The develop
branch is set to ContinuousDeployment
mode by default as we have
found that is generally what is needed when using GitFlow.
To see the effective configuration (defaults and overrides), you can run
gitversion /showConfig
.
The following supported workflow configurations are available in GitVersion and can be referenced by the workflow property:
- GitFlow (GitFlow/v1)
- GitHubFlow (GitHubFlow/v1)
Example of using a GitHubFlow
workflow with a different tag-prefix
:
workflow: GitHubFlow/v1
tag-prefix: '[abc]'
The built-in configuration for the GitFlow
workflow (workflow: GitFlow/v1
) looks like:
assembly-versioning-scheme: MajorMinorPatch
assembly-file-versioning-scheme: MajorMinorPatch
tag-prefix: '[vV]?'
version-in-branch-pattern: (?<version>[vV]?\d+(\.\d+)?(\.\d+)?).*
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)'
tag-pre-release-weight: 60000
commit-date-format: yyyy-MM-dd
merge-message-formats: {}
update-build-number: true
semantic-version-format: Strict
strategies:
- Fallback
- ConfiguredNextVersion
- MergeMessage
- TaggedCommit
- TrackReleaseBranches
- VersionInBranchName
branches:
develop:
mode: ContinuousDelivery
label: alpha
increment: Minor
prevent-increment:
when-current-commit-tagged: false
track-merge-target: true
track-merge-message: true
regex: ^dev(elop)?(ment)?$
source-branches:
- main
is-source-branch-for: []
tracks-release-branches: true
is-release-branch: false
is-main-branch: false
pre-release-weight: 0
main:
label: ''
increment: Patch
prevent-increment:
of-merged-branch: true
track-merge-target: false
track-merge-message: true
regex: ^master$|^main$
source-branches: []
is-source-branch-for: []
tracks-release-branches: false
is-release-branch: false
is-main-branch: true
pre-release-weight: 55000
release:
mode: ManualDeployment
label: beta
increment: Minor
prevent-increment:
of-merged-branch: true
when-current-commit-tagged: false
track-merge-target: false
regex: ^releases?[/-](?<BranchName>.+)
source-branches:
- main
- support
is-source-branch-for: []
tracks-release-branches: false
is-release-branch: true
is-main-branch: false
pre-release-weight: 30000
feature:
mode: ManualDeployment
label: '{BranchName}'
increment: Inherit
prevent-increment:
when-current-commit-tagged: false
track-merge-message: true
regex: ^features?[/-](?<BranchName>.+)
source-branches:
- develop
- main
- release
- support
- hotfix
is-source-branch-for: []
is-main-branch: false
pre-release-weight: 30000
pull-request:
mode: ContinuousDelivery
label: PullRequest
increment: Inherit
prevent-increment:
of-merged-branch: true
when-current-commit-tagged: false
label-number-pattern: '[/-](?<number>\d+)'
track-merge-message: true
regex: ^(pull|pull\-requests|pr)[/-]
source-branches:
- develop
- main
- release
- feature
- support
- hotfix
is-source-branch-for: []
pre-release-weight: 30000
hotfix:
mode: ManualDeployment
label: beta
increment: Inherit
prevent-increment:
when-current-commit-tagged: false
regex: ^hotfix(es)?[/-](?<BranchName>.+)
source-branches:
- main
- support
is-source-branch-for: []
is-release-branch: true
is-main-branch: false
pre-release-weight: 30000
support:
label: ''
increment: Patch
prevent-increment:
of-merged-branch: true
track-merge-target: false
regex: ^support[/-](?<BranchName>.+)
source-branches:
- main
is-source-branch-for: []
tracks-release-branches: false
is-release-branch: false
is-main-branch: true
pre-release-weight: 55000
unknown:
mode: ManualDeployment
label: '{BranchName}'
increment: Inherit
prevent-increment:
when-current-commit-tagged: true
regex: (?<BranchName>.+)
source-branches:
- main
- develop
- release
- feature
- pull-request
- hotfix
- support
is-source-branch-for: []
is-main-branch: false
ignore:
sha: []
mode: ContinuousDelivery
label: '{BranchName}'
increment: Inherit
prevent-increment:
of-merged-branch: false
when-branch-merged: false
when-current-commit-tagged: true
track-merge-target: false
track-merge-message: true
commit-message-incrementing: Enabled
regex: ''
source-branches: []
is-source-branch-for: []
tracks-release-branches: false
is-release-branch: false
is-main-branch: false
The supported built-in configuration for the GitHubFlow
workflow (workflow: GitHubFlow/v1
) looks like:
assembly-versioning-scheme: MajorMinorPatch
assembly-file-versioning-scheme: MajorMinorPatch
tag-prefix: '[vV]?'
version-in-branch-pattern: (?<version>[vV]?\d+(\.\d+)?(\.\d+)?).*
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)'
tag-pre-release-weight: 60000
commit-date-format: yyyy-MM-dd
merge-message-formats: {}
update-build-number: true
semantic-version-format: Strict
strategies:
- Fallback
- ConfiguredNextVersion
- MergeMessage
- TaggedCommit
- TrackReleaseBranches
- VersionInBranchName
branches:
main:
label: ''
increment: Patch
prevent-increment:
of-merged-branch: true
track-merge-target: false
track-merge-message: true
regex: ^master$|^main$
source-branches: []
is-source-branch-for: []
tracks-release-branches: false
is-release-branch: false
is-main-branch: true
pre-release-weight: 55000
release:
mode: ManualDeployment
label: beta
increment: Patch
prevent-increment:
of-merged-branch: true
when-branch-merged: false
when-current-commit-tagged: false
track-merge-target: false
track-merge-message: true
regex: ^releases?[/-](?<BranchName>.+)
source-branches:
- main
is-source-branch-for: []
tracks-release-branches: false
is-release-branch: true
is-main-branch: false
pre-release-weight: 30000
feature:
mode: ManualDeployment
label: '{BranchName}'
increment: Inherit
prevent-increment:
when-current-commit-tagged: false
regex: ^features?[/-](?<BranchName>.+)
source-branches:
- main
- release
is-source-branch-for: []
track-merge-message: true
is-main-branch: false
pre-release-weight: 30000
pull-request:
mode: ContinuousDelivery
label: PullRequest
increment: Inherit
prevent-increment:
of-merged-branch: true
when-current-commit-tagged: false
label-number-pattern: '[/-](?<number>\d+)'
regex: ^(pull|pull\-requests|pr)[/-]
source-branches:
- main
- release
- feature
is-source-branch-for: []
track-merge-message: true
pre-release-weight: 30000
unknown:
mode: ManualDeployment
label: '{BranchName}'
increment: Inherit
prevent-increment:
when-current-commit-tagged: false
regex: (?<BranchName>.+)
source-branches:
- main
- release
- feature
- pull-request
is-source-branch-for: []
track-merge-message: false
is-main-branch: false
ignore:
sha: []
mode: ContinuousDelivery
label: '{BranchName}'
increment: Inherit
prevent-increment:
of-merged-branch: false
when-branch-merged: false
when-current-commit-tagged: true
track-merge-target: false
track-merge-message: true
commit-message-incrementing: Enabled
regex: ''
source-branches: []
is-source-branch-for: []
tracks-release-branches: false
is-release-branch: false
is-main-branch: false
The details of the available options are as follows:
The base template of the configuration to use. Possible values are GitFlow/v1
or GitHubFlow/v1
. Defaults to GitFlow/v1
if not set. To create a configuration from scratch without using a base template, please specify an empty string.
Allows you to bump the next version explicitly. Useful for bumping main
or a
feature branch with breaking changes (i.e., a major increment), indicating what
the next git tag
is going to be.
next-version
is not a permanent replacement for git tag
and should only be
used intermittently. Since version 5.5 GitVersion supports next-version
with
mode: Mainline
and should not be treated as a "base version".
If you are using next-version
and are experiencing weird versioning behaviour,
please remove it, create a git tag
with an appropriate version number on an
appropriate historical commit and see if that resolves any versioning issues
you may have.
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
while still updating the AssemblyFileVersion
and AssemblyInformationVersion
attributes. Valid values: MajorMinorPatchTag
, MajorMinorPatch
, MajorMinor
,
Major
, None
.
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
AssemblyVersion
and AssemblyInformationVersion
attributes. Valid values:
MajorMinorPatchTag
, MajorMinorPatch
, MajorMinor
, Major
, None
.
Specifies the format of AssemblyFileVersion
and
overwrites the value of assembly-file-versioning-scheme
.
Expressions in curly braces reference one of the variables
or a process-scoped environment variable (when prefixed with env:
). For example,
# use a variable if non-null or a fallback value otherwise
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}'
# use an environment variable if available or a fallback value otherwise
assembly-file-versioning-format: '{Major}.{Minor}.{Patch}.{env:BUILD_NUMBER ?? 42}'
Specifies the format of AssemblyVersion
and
overwrites the value of assembly-versioning-scheme
.
Follows the same formatting semantics as assembly-file-versioning-format
.
Specifies the format of AssemblyInformationalVersion
.
Follows the same formatting semantics as assembly-file-versioning-format
.
The default value is {InformationalVersion}
.
Sets the mode
of how GitVersion should create a new version. Read more at
deployment modes.
The part of the SemVer to increment when GitVersion detects it needs to be
increased, such as for commits after a tag: Major
, Minor
, Patch
, None
.
The special value Inherit
means that GitVersion should find the parent branch
(i.e. the branch where the current branch was branched from), and use its values
for increment or other branch related properties.
A regular expression which is used to trim Git tags before processing (e.g.,
v1.0.0). The default value is [vV]
.
A regular expression which is used to determine the version number in the branch
name or commit message (e.g., v1.0.0-LTS). This setting only applies on branches
where the option is-release-branch
is set to true
. The default value is
(?<version>[vV]?\d+(\.\d+)?(\.\d+)?).*
.
The regex to match commit messages with to perform a major version increment.
Default set to '\+semver:\s?(breaking|major)'
, which will match occurrences of
+semver: major
and +semver: breaking
in a commit message.
The regex to match commit messages with to perform a minor version increment.
Default set to '\+semver:\s?(feature|minor)'
, which will match occurrences of
+semver: feature
and +semver: minor
in a commit message.
The regex to match commit messages with to perform a patch version increment.
Default set to '\+semver:\s?(fix|patch)'
, which will match occurrences of
+semver: fix
and +semver: patch
in a commit message.
Used to tell GitVersion not to increment when in Mainline development mode.
Default \+semver:\s?(none|skip)
, which will match occurrences of +semver: none
and +semver: skip
When a commit matches both the no-bump-message
and any combination of
the version-bump-message
, no-bump-message
takes precedence and no increment is applied.
The pre-release weight in case of tagged commits. If the value is not set in the
configuration, a default weight of 60000 is used instead. If the
WeightedPreReleaseNumber
variable is 0 and this parameter is set,
its value is used. This helps if your branching model is GitFlow and the last
release build, which is often tagged, can utilize this parameter to produce a
monotonically increasing build number.
Sets whether it should be possible to increment the version with special syntax
in the commit message. See the *-version-bump-message
options above for
details on the syntax. Default set to Enabled
; set to Disabled
to disable.
Sets the format which will be used to format the CommitDate
output variable.
The header property for the ignore
configuration.
:::{.alert .alert-info} Note: When ignoring a commit or a range of commits, they are only ignored in the search for a version source, not when calculating other parts of the version number, such as build metadata. :::
A sequence of SHAs to be excluded from the version calculations. Useful when there is a rogue commit in history yielding a bad version. You can use either style below:
ignore:
sha: [e7bc24c0f34728a25c9187b8d0b041d935763e3a, 764e16321318f2fdb9cdeaa56d1156a1cba307d7]
or
ignore:
sha:
- e7bc24c0f34728a25c9187b8d0b041d935763e3a
- 764e16321318f2fdb9cdeaa56d1156a1cba307d7
Date and time in the format yyyy-MM-ddTHH:mm:ss
(eg commits-before: 2015-10-23T12:23:15
) to setup an exclusion range. Effectively any commit before
commits-before
will be ignored.
Custom merge message formats to enable identification of merge messages that do not follow the built-in conventions. Entries should be added as key-value pairs where the value is a regular expression. e.g.
merge-message-formats:
tfs: '^Merged (?:PR (?<PullRequestNumber>\d+)): Merge (?<SourceBranch>.+) to (?<TargetBranch>.+)'
The regular expression should contain the following capture groups:
SourceBranch
- Identifies the source branch of the mergeTargetBranch
- Identifies the target branch of the mergePullRequestNumber
- Captures the pull-request number
Custom merge message formats are evaluated before any built in formats. Support for Conventional Commits can be configured.
Configures GitVersion to update the build number or not when running on a build server.
Then we have branch specific configuration, which looks something like this:
:::{.alert .alert-info} Note
v4 changed from using regexes for keys, to named configs :::
If you have branch specific configuration upgrading to v4 will force you to upgrade.
branches:
main:
regex: ^master$|^main$
mode: ContinuousDelivery
label: ''
increment: Patch
prevent-increment-of-merged-branch-version: true
track-merge-target: false
source-branches: [ 'develop', 'release' ]
tracks-release-branches: false
is-release-branch: false
is-main-branch: true
pre-release-weight: 55000
develop:
regex: ^dev(elop)?(ment)?$
mode: ContinuousDeployment
label: alpha
increment: Minor
prevent-increment-of-merged-branch-version: false
track-merge-target: true
source-branches: []
tracks-release-branches: true
is-release-branch: false
is-main-branch: false
pre-release-weight: 0
release:
regex: ^releases?[/-]
mode: ContinuousDelivery
label: beta
increment: None
prevent-increment-of-merged-branch-version: true
track-merge-target: false
source-branches: [ 'develop', 'main', 'support', 'release' ]
tracks-release-branches: false
is-release-branch: true
is-main-branch: false
pre-release-weight: 30000
feature:
regex: ^features?[/-]
mode: ContinuousDelivery
label: '{BranchName}'
increment: Inherit
source-branches: [ 'develop', 'main', 'release', 'feature', 'support', 'hotfix' ]
pre-release-weight: 30000
pull-request:
regex: ^(pull|pull\-requests|pr)[/-]
mode: ContinuousDelivery
label: PullRequest
increment: Inherit
label-number-pattern: '[/-](?<number>\d+)[-/]'
source-branches: [ 'develop', 'main', 'release', 'feature', 'support', 'hotfix' ]
pre-release-weight: 30000
hotfix:
regex: ^hotfix(es)?[/-]
mode: ContinuousDelivery
label: beta
increment: Inherit
source-branches: [ 'release', 'main', 'support', 'hotfix' ]
pre-release-weight: 30000
support:
regex: ^support[/-]
mode: ContinuousDelivery
label: ''
increment: Patch
prevent-increment-of-merged-branch-version: true
track-merge-target: false
source-branches: [ 'main' ]
tracks-release-branches: false
is-release-branch: false
is-main-branch: true
pre-release-weight: 55000
If you don't specify the regex, the built-in for that branch config will be used (recommended).
We don't envision many people needing to change most of these configuration values, but here they are if you need to:
This is the regex which is used to match the current branch to the correct branch configuration.
Named groups can be used to dynamically label pre-releases based on the branch name, or parts of it. See Label for more details and examples.
Because Git commits only refer to parent commits (not branches) GitVersion sometimes cannot tell which branch the current branch was branched from.
Take this commit graph
* release/v1.0.0 * feature/foo
| ________________/
|/
*
*
* (main)
By looking at this graph, you cannot tell which of these scenarios happened:
- feature/foo branches off release/v1.0.0
- Branch release/v1.0.0 from main
- Branch feature/foo from release/v1.0.0
- Add a commit to both release/v1.0.0 and feature/foo
- release/v1.0.0 is the base for feature/foo
- release/v1.0.0 branches off feature/foo
- Branch feature/foo from main
- Branch release/v1.0.0 from feature/foo
- Add a commit to both release/v1.0.0 and feature/foo
- feature/foo is the base for release/v1.0.0
Or put more simply, you cannot tell which branch was created first,
release/v1.0.0
or feature/foo
.
To resolve this issue, we give GitVersion a hint about our branching workflows by telling it what types of branches a branch can be created from. For example, feature branches are, by default, configured to have the following source branches:
source-branches: ['main', 'develop', 'feature', 'hotfix', 'support']
This means that we will never bother to evaluate pull request branches as merge base options and being explicit in this way also improves the performance of GitVersion.
The reverse of source-branches
. This property was introduced to keep it easy
to extend GitVersion's config.
It exists to make it easier to extend GitVersion's configuration. If only
source-branches
exists and you add a new branch type, for instance
unstable/
, you then need to re-define the source-branches
configuration
value for existing branches (like feature/) to now include the new unstable
branch.
A complete example:
branches:
unstable:
regex: ...
is-source-branch-for: ['main', 'develop', 'feature', 'hotfix', 'support']
Without this configuration value you would have to do:
branches:
unstable:
regex:
feature:
source-branches: ['unstable', 'develop', 'feature', 'hotfix', 'support']
release:
source-branches: ['unstable', 'develop']
etc...
The header for all the individual branch configuration.
Same as for the global configuration, explained above.
The pre-release label to use for this branch. Use the value {BranchName}
as a placeholder to
insert the value of the named group BranchName
from the regular expression.
For example: branch feature/foo
would become a pre-release label
of alpha.foo
with label: 'alpha.{BranchName}'
and regex: '^features?[/-](?<BranchName>.+)'
.
Another example: branch features/sc-12345/some-description
would become a pre-release label of sc-12345
with label: '{StoryNo}'
and regex: '^features?[/-](?<StoryNo>sc-\d+)[-/].+'
.
Note: To clear a default use an empty string: label: ''
Same as for the global configuration, explained above.
The increment of the branch merged to will be ignored, regardless of whether the merged branch has a version number or not, when this branch related property is set to true on the target branch.
When release-2.0.0
is merged into main, we want main to build 2.0.0
. If
release-2.0.0
is merged into develop we want it to build 2.1.0
, this option
prevents incrementing after a versioned branch is merged.
In a GitFlow-based repository, setting this option can have implications on the
CommitsSinceVersionSource
output variable. It can rule out a potentially
better version source proposed by the MergeMessageBaseVersionStrategy
. For
more details and an in-depth analysis, please see the discussion.
The increment of the merged branch will be ignored when this branch related property is set to true
on the source branch.
This branch related property controls the behvior whether to use the tagged (value set to true) or the incremented (value set to false) semantic version. Defaults to true.
Pull requests require us to extract the pre-release number out of the branch
name so refs/pulls/534/merge
builds as PullRequest.534
. This is a regex with
a named capture group called number
.
If the branch mode
is set to ContinuousDeployment
, then the extracted
number
is appended to the name of the pre-release label and the number portion
is the number of commits since the last label. This enables consecutive commits to
the pull request branch to generate unique full semantic version numbers when
the branch is configured to use ContinuousDeployment mode.
Example usage:
branches:
pull-request:
mode: ContinuousDeployment
label: PullRequest
increment: Inherit
track-merge-target: true
label-number-pattern: '[/-](?<number>\d+)[-/]'
Strategy which will look for tagged merge commits directly off the current
branch. For example develop
→ release/1.0.0
→ merge into main
and tag
1.0.0
. The tag is not on develop, but develop should be version 1.0.0
now.
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. Consider we have a main branch and a release/1.0.0
branch and
merge changes from release/1.0.0
to the main
branch. If track-merge-message
is set to true
then the next version will
be 1.0.0
otherwise 0.0.1
.
Indicates this branch config represents develop in GitFlow.
Indicates this branch config represents a release branch in GitFlow.
This indicates that this branch is a main branch. By default main
and support/*
are main branches.
Provides a way to translate the PreReleaseLabel
(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
"1.2.3-beta.1" and thus e.g. "1.2.3-alpha.4" and "1.2.3-beta.4" would have the
same file version: "1.2.3.4". One of the ways to use this value is to set
assembly-file-versioning-format: {Major}.{Minor}.{Patch}.{WeightedPreReleaseNumber}
. If the pre-release-weight
is set, it would be added to the PreReleaseNumber
to get a final
AssemblySemFileVer
, otherwise a branch specific default for
pre-release-weight
will be used in the calculation. Related Issues 1145
and 1366.
Specifies the semantic version format that is used when parsing the string.
Can be Strict
- using the regex
or Loose
the old way of parsing. The default if not specified is Strict
Example of invalid Strict
, but valid Loose
1.2-alpha4
01.02.03-rc03
1.2.3.4
Specifies which version strategy implementation (one ore more) will be used to determine the next version. Following values are supported and can be combined:
- Fallback
- ConfiguredNextVersion
- MergeMessage
- TaggedCommit
- TrackReleaseBranches
- VersionInBranchName
- TrunkBased