Skip to content

Commit 18b6b46

Browse files
asbjornuasbjornu
committed
Wrap configuration at 80 characters
1 parent 18cb66c commit 18b6b46

File tree

1 file changed

+113
-48
lines changed

1 file changed

+113
-48
lines changed

‎docs/configuration.md

Lines changed: 113 additions & 48 deletions
Original file line numberDiff line numberDiff line change
@@ -1,58 +1,107 @@
11
# Configuration
2-
GitVersion 3.0 is mainly powered by configuration and no longer has branching strategies hard coded.
2+
GitVersion 3.0 is mainly powered by configuration and no longer has branching
3+
strategies hard coded.
34

45
## Configuration tool
5-
If you run `GitVersion init` you will be launched into a configuration tool, it can help you configure GitVersion the way you want it.
6+
If you run `GitVersion init` you will be launched into a configuration tool, it
7+
can help you configure GitVersion the way you want it.
68

7-
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.
9+
Once complete, the `init` command will create a `GitVersion.yml` file in the
10+
working directory. It can be the root repository directory or any subdirectory
11+
in case you have a single repository for more than one project or are restricted
12+
to commit into a subdirectory.
813

9-
**Note:** GitVersion ships with internal default configuration which works with GitHubFlow and GitFlow, probably with others too.
14+
**Note:** GitVersion ships with internal default configuration which works with
15+
GitHubFlow and GitFlow, probably with others too.
1016

11-
The *develop* branch is set to `ContinuousDeployment` mode by default as we have found that is generally what is needed when using GitFlow.
17+
The *develop* branch is set to `ContinuousDeployment` mode by default as we have
18+
found that is generally what is needed when using GitFlow.
1219

13-
You can run `GitVersion /showConfig` to see the effective configuration (defaults + overrides)
20+
You can run `GitVersion /showConfig` to see the effective configuration
21+
(defaults + overrides).
1422

15-
To create your config file just type `GitVersion init` in your repo directory after installing via chocolatey and we will create a sample (but commented out) config file.
16-
Uncomment and modify as you need.
23+
To create your config file just type `GitVersion init` in your repo directory
24+
after installing via chocolatey and a minimal `GitVersion.yml` configuration
25+
file will be created. Modify this as you need.
1726

1827
## Global configuration
1928
The global configuration options are:
2029

21-
- **`next-version:`** Allows you to bump the next version explicitly, useful for bumping `master` or a feature with breaking changes a major increment.
22-
23-
- **`assembly-versioning-scheme:`** When updating assembly info 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.
24-
25-
- **`assembly-informational-format:`** Set this to any of the available [variables](/more-info/variables) to change the value of the `AssemblyInformationalVersion` attribute. Default set to `{InformationalVersion}`. It also supports string interpolation (`{MajorMinorPatch}+{Branch}`)
26-
27-
- **`mode:`** Sets the mode of how GitVersion should create a new version. Read more at [versioning mode](/reference/versioning-mode.md).
28-
29-
- **`continuous-delivery-fallback-tag:`** When using `mode: ContinuousDeployment`, the value specified will be used as the pre-release tag for branches which do not have one specified. Default set to `ci`.
30-
31-
- **`tag-prefix:`** A regex which is used to trim git tags before processing (eg v1.0.0). Default is `[vV]` though this is just for illustrative purposes as we do a IgnoreCase match and could be `v`.
32-
33-
- **`major-version-bump-message:`** 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.
34-
35-
- **`minor-version-bump-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.
36-
37-
- **`patch-version-bump-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.
38-
39-
- **`no-bump-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`
40-
41-
- **`legacy-semver-padding:`** The number of characters to pad `LegacySemVer` to in the `LegacySemVerPadded` [variable](/more-info/variables). Is default set to `4`, which will pad the `LegacySemVer` value of `3.0.0-beta1` to `3.0.0-beta0001`.
42-
43-
- **`build-metadata-padding:`** The number of characters to pad `BuildMetaData` to in the `BuildMetaDataPadded` [variable](/more-info/variables). Is default set to `4`, which will pad the `BuildMetaData` value of `1` to `0001`.
44-
45-
- **`commits-since-version-source-padding:`** The number of characters to pad `CommitsSinceVersionSource` to in the `CommitsSinceVersionSourcePadded` [variable](/more-info/variables). Is default set to `4`, which will pad the `CommitsSinceVersionSource` value of `1` to `0001`.
46-
47-
- **`commit-message-incrementing:`** 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.
30+
- **`next-version:`** Allows you to bump the next version explicitly, useful
31+
for bumping `master` or a feature with breaking changes a major increment.
32+
33+
- **`assembly-versioning-scheme:`** When updating assembly info tells
34+
GitVersion how to treat the `AssemblyVersion` attribute. Useful to lock the
35+
major when using Strong Naming. Note: you can use `None` to skip updating the
36+
`AssemblyVersion` while still updating the `AssemblyFileVersion` and
37+
`AssemblyInformationVersion` attributes.
38+
39+
- **`assembly-informational-format:`** Set this to any of the available
40+
[variables](/more-info/variables) to change the value of the
41+
`AssemblyInformationalVersion` attribute. Default set to
42+
`{InformationalVersion}`. It also supports string interpolation
43+
(`{MajorMinorPatch}+{Branch}`)
44+
45+
- **`mode:`** Sets the mode of how GitVersion should create a new version. Read
46+
more at [versioning mode](/reference/versioning-mode.md).
47+
48+
- **`continuous-delivery-fallback-tag:`** When using `mode:
49+
ContinuousDeployment`, the value specified will be used as the pre-release tag
50+
for branches which do not have one specified. Default set to `ci`.
51+
52+
- **`tag-prefix:`** A regex which is used to trim git tags before processing (eg
53+
v1.0.0). Default is `[vV]` though this is just for illustrative purposes as we
54+
do a IgnoreCase match and could be `v`.
55+
56+
- **`major-version-bump-message:`** The regex to match commit messages with to
57+
perform a major version increment. Default set to
58+
`'\+semver:\s?(breaking|major)'`, which will match occurrences of
59+
`+semver: major` and `+semver: breaking` in a commit message.
60+
61+
- **`minor-version-bump-message:`** The regex to match commit messages with to
62+
perform a minor version increment. Default set to
63+
`'\+semver:\s?(feature|minor)'`, which will match occurrences of
64+
`+semver: feature` and `+semver: minor` in a commit message.
65+
66+
- **`patch-version-bump-message:`** The regex to match commit messages with to
67+
perform a patch version increment. Default set to `'\+semver:\s?(fix|patch)'`,
68+
which will match occurrences of `+semver: fix` and `+semver: patch` in a
69+
commit message.
70+
71+
- **`no-bump-message:`** Used to tell GitVersion not to increment when in
72+
Mainline development mode. Default `\+semver:\s?(none|skip)`, which will match
73+
occurrences of `+semver: none` and `+semver: skip`
74+
75+
- **`legacy-semver-padding:`** The number of characters to pad `LegacySemVer` to
76+
in the `LegacySemVerPadded` [variable](/more-info/variables). Is default set
77+
to `4`, which will pad the `LegacySemVer` value of `3.0.0-beta1` to
78+
`3.0.0-beta0001`.
79+
80+
- **`build-metadata-padding:`** The number of characters to pad `BuildMetaData`
81+
to in the `BuildMetaDataPadded` [variable](/more-info/variables). Is default
82+
set to `4`, which will pad the `BuildMetaData` value of `1` to `0001`.
83+
84+
- **`commits-since-version-source-padding:`** The number of characters to pad
85+
`CommitsSinceVersionSource` to in the `CommitsSinceVersionSourcePadded`
86+
[variable](/more-info/variables). Is default set to `4`, which will pad the
87+
`CommitsSinceVersionSource` value of `1` to `0001`.
88+
89+
- **`commit-message-incrementing:`** Sets whether it should be possible to
90+
increment the version with special syntax in the commit message. See the
91+
`*-version-bump-message` options above for details on the syntax. Default set
92+
to `Enabled`; set to `Disabled` to disable.
4893

4994
- **`ignore:`** The header for ignore configuration
50-
- **`sha:`** A sequence of SHAs to be excluded from the version calculations. Useful when there is a rogue commit in history yielding a bad version.
51-
- **`commits-before:`** 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 < `commits-before` will be ignored.
95+
- **`sha:`** A sequence of SHAs to be excluded from the version calculations.
96+
Useful when there is a rogue commit in history yielding a bad version.
97+
- **`commits-before:`** Date and time in the format `yyyy-MM-ddTHH:mm:ss` (eg
98+
`commits-before: 2015-10-23T12:23:15`) to setup an exclusion range.
99+
Effectively any commit < `commits-before` will be ignored.
52100

53101
- **`is-develop:`** Indicates this branch config represents develop in GitFlow
54102

55-
**`is-release-branch:`** Indicates this branch config represents a release branch in GitFlow
103+
- **`is-release-branch:`** Indicates this branch config represents a release
104+
branch in GitFlow
56105

57106
## Branch configuration
58107

@@ -78,19 +127,31 @@ The options in here are:
78127
- **`mode:`** Same as above
79128

80129
- **`tag:`** The pre release tag to use for this branch.
81-
Use the value `useBranchName` to use the branch name instead. For example `feature/foo` would become a pre-release tag of `foo` with this value.
82-
Use the value `{BranchName}` as a placeholder to insert the branch name. For example `feature/foo` would become a pre-release tag of `alpha.foo` with the value of `alpha.{BranchName}`.
130+
Use the value `useBranchName` to use the branch name instead. For example
131+
`feature/foo` would become a pre-release tag of `foo` with this value.
132+
Use the value `{BranchName}` as a placeholder to insert the branch name. For
133+
example `feature/foo` would become a pre-release tag of `alpha.foo` with the
134+
value of `alpha.{BranchName}`.
83135
**Note:** To clear a default use an empty string: `tag: ""`
84136

85-
- **`increment:`** the part of the SemVer to increment when GitVersion detects it needs to be (i.e commit after a tag)
137+
- **`increment:`** the part of the SemVer to increment when GitVersion detects
138+
it needs to be (i.e commit after a tag)
86139

87-
- **`prevent-increment-of-merged-branch-version:`** When `release-2.0.0` is merged into master, we want master to build `2.0.0`.
88-
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
140+
- **`prevent-increment-of-merged-branch-version:`** When `release-2.0.0` is
141+
merged into master, we want master to build `2.0.0`. If `release-2.0.0` is
142+
merged into develop we want it to build `2.1.0`, this option prevents
143+
incrementing after a versioned branch is merged
89144

90-
- **`tag-number-pattern:`** Pull requests require us to extract the pre-release number out of the branch name so `refs/pulls/534/merge` builds as `PullRequest.534`.
145+
- **`tag-number-pattern:`** Pull requests require us to extract the pre-release
146+
number out of the branch name so `refs/pulls/534/merge` builds as
147+
`PullRequest.534`.
91148
This is a regex with a named capture group called `number`
92-
If the branch mode is set to ContinuousDeployment, then the extracted `number` is appended to the name of the pre-release tag and the number portion is the number of commits since the last tag.
93-
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.
149+
If the branch mode is set to ContinuousDeployment, then the extracted
150+
`number` is appended to the name of the pre-release tag and the number
151+
portion is the number of commits since the last tag.
152+
This enables consecutive commits to the pull request branch to generate
153+
unique full semantic version numbers when the branch is configured to use
154+
ContinuousDeployment mode.
94155
Example usage:
95156
```yaml
96157
branches:
@@ -102,6 +163,10 @@ branches:
102163
tag-name-pattern: '[/-](?<number>\d+)[-/]'
103164
```
104165

105-
- **`track-merge-target:`** Strategy which will look for tagged merge commits directly off the current branch. For example `develop` → `release/1.0.0` → merge into `master` and tag `1.0.0`. The tag is *not* on develop, but develop should be version `1.0.0` now.
166+
- **`track-merge-target:`** Strategy which will look for tagged merge commits
167+
directly off the current branch. For example `develop` → `release/1.0.0` →
168+
merge into `master` and tag `1.0.0`. The tag is *not* on develop, but develop
169+
should be version `1.0.0` now.
106170

107-
We don't envision many people needing to change most of these configuration values, but they are there if you need to.
171+
We don't envision many people needing to change most of these configuration
172+
values, but they are there if you need to.

0 commit comments

Comments
 (0)