diff --git a/.markdownlint.json b/.markdownlint.json index 7ab1720b67..08d535e1cb 100644 --- a/.markdownlint.json +++ b/.markdownlint.json @@ -1,3 +1,4 @@ { - "MD026": false + "MD026": false, + "MD041": false } diff --git a/BREAKING_CHANGES.md b/BREAKING_CHANGES.md index 66e1d4697b..9f0db2b22b 100644 --- a/BREAKING_CHANGES.md +++ b/BREAKING_CHANGES.md @@ -1,74 +1,81 @@ ## v6.0.0 ### Platforms -* Drop support for .NET Framework 4.8, .NET Core 3.1 and .NET 5.0. Changed the project targets to .NET 6.0 or later. + +* Drop support for .NET Framework 4.8, .NET Core 3.1 and .NET 5.0. Changed the project targets to .NET 6.0 or later. ### Caching -* Refactor caching system in GitVersion to use json files instead of yaml files. This change is not backwards compatible with the old caching system. + +* Refactor caching system in GitVersion to use json files instead of yaml files. This change is not backwards compatible with the old caching system. ### Configuration changes: -* The configuration properties `continuous-delivery-fallback-tag`, `tag-number-pattern`, and `tag` were renamed to `continuous-delivery-fallback-label`, `label-number-pattern`, and `label` respectively. `tag-pre-release-weight` and `tag-prefix` remained as they were as they are referring to a Git tag. -* When using a commit message that matches **both** `*-version-bump-message` and `no-bump-message`, there is no increment for that commit. In other words, `no-bump-message` now takes precedence over `*-version-bump-message`. -* The fallback version strategy now returns `0.0.0` and is flagged with `ShouldIncrement` equal to `true`. This yields the version `0.1.0` on the `develop` branch (`IncrementStrategy.Minor` by default) and `0.0.1` on the `main` branch (`IncremetnStrategy.Patch` by default). -* The current branch (child) inherits its configuration from the source (parent) branch if the `increment` strategy is set to `Inherit`. This makes branch configuration recursive, simpler, more intuitive, more flexible, and more robust. -* Instead of having a single effective configuration, we now have one effective configuration per branch where the increment strategy is not set to `inherit`. -* The new implementation of the branch configuration inheritance affects per default only the pull-requests, hotfix and feature branches. In this case the next version will be generated like the child branch is not existing and the commits have been made on the source branch. - * The following example illustrates this behavior. On the feature branch the semantic version `1.1.0-just-a-test.1+2` will now be generated instead of version `1.0.0-just-a-test.1+3` previously: - ``` + +* The configuration properties `continuous-delivery-fallback-tag`, `tag-number-pattern`, and `tag` were renamed to `continuous-delivery-fallback-label`, `label-number-pattern`, and `label` respectively. `tag-pre-release-weight` and `tag-prefix` remained as they were as they are referring to a Git tag. +* When using a commit message that matches **both** `*-version-bump-message` and `no-bump-message`, there is no increment for that commit. In other words, `no-bump-message` now takes precedence over `*-version-bump-message`. +* The fallback version strategy now returns `0.0.0` and is flagged with `ShouldIncrement` equal to `true`. This yields the version `0.1.0` on the `develop` branch (`IncrementStrategy.Minor` by default) and `0.0.1` on the `main` branch (`IncremetnStrategy.Patch` by default). +* The current branch (child) inherits its configuration from the source (parent) branch if the `increment` strategy is set to `Inherit`. This makes branch configuration recursive, simpler, more intuitive, more flexible, and more robust. +* Instead of having a single effective configuration, we now have one effective configuration per branch where the increment strategy is not set to `inherit`. +* The new implementation of the branch configuration inheritance affects per default only the pull-requests, hotfix and feature branches. In this case the next version will be generated like the child branch is not existing and the commits have been made on the source branch. + * The following example illustrates this behavior. On the feature branch the semantic version `1.1.0-just-a-test.1+2` will now be generated instead of version `1.0.0-just-a-test.1+3` previously: + + ``` log * 1f1cfb4 52 minutes ago (HEAD -> feature/just-a-test) * 1f9654d 54 minutes ago (release/1.1.0) * be72411 56 minutes ago (develop) * 14800ff 58 minutes ago (tag: 1.0.0, main) ``` -* A new `unknown` branch magic string has been introduced to give the user the possibility to specify the branch configuration for a branch which is not known. A branch is not known if only the regular expression of the branch configuration with the name `unknown` is matching. Please notice that this branch configuration behaves like any other branch configurations. -* Additional `fallback` branch configuration properties have been introduced at the root to define base properties which will be inherit to the branch configurations. That means if no other branch configuration in the inheritance line defines the given property the fallback property applies. Notice that the inheritance tree can be controlled using the increment strategy property in the branch configuration section. - * The following example illustrates this behavior. The hotfix branch configuration overrides the main branch configuration and the result overrides the fallback branch configuration. - ``` + +* A new `unknown` branch magic string has been introduced to give the user the possibility to specify the branch configuration for a branch which is not known. A branch is not known if only the regular expression of the branch configuration with the name `unknown` is matching. Please notice that this branch configuration behaves like any other branch configurations. +* Additional `fallback` branch configuration properties have been introduced at the root to define base properties which will be inherit to the branch configurations. That means if no other branch configuration in the inheritance line defines the given property the fallback property applies. Notice that the inheritance tree can be controlled using the increment strategy property in the branch configuration section. + * The following example illustrates this behavior. The hotfix branch configuration overrides the main branch configuration and the result overrides the fallback branch configuration. + + ``` log * 1f1cfb4 52 minutes ago (HEAD -> hotfix/just-a-test) * 14800ff 58 minutes ago (tag: 1.0.0, main) ``` -* When overriding the configuration with e.g. GitVersion.yaml the software distinguishes between properties who are not existent and properties who are `null`. This is especially important if the user wants to define branch related configuration which are marked with `increment` strategy `Inherit`. -* Following root configuration properties have been removed: - * continuous-delivery-fallback-tag -* A new branch related property with name `track-merge-message` has been introduced. 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. In this scenario the merge message will be interpreted as a next version `1.0.0` when `track-merge-message` is set to `true` otherwise `0.0.1`. -* The pre-release tags are only considered when they are matching with the label name of the branch. This has an effect on the way how the `CommitCountSource` will be determined. -* The process of increasing the version with bump message when `CommitMessageIncrementing` is enabled and increment strategy is `None` has been changed. -* A new configuration property with name `version-in-branch-pattern` has been introduced. This setting only applies on branches where the option `is-release-branch` is set to `true`. Please notice that the branch name needs to be defined after the version number by default (instead of `support/lts-2.0.0` please name the branch like `support/2.0.0-lts`). -* The `is-release-branch` property of the `hotfix` branch setting has been changed from `false` to `true`. If present the hotfix number will be considered now by default. -* In the GitHub and the Git Flow workflows the `label` property is by default set to an empty string on the `main` branch. This yields to a pre-release version on `main` with an empty tag. Instead of for instance `1.0.1+46` GitVersion generates the full semantic version `1.0.1-46` instead. This behavior can be changed to generate only stable versions (no pre-release version) with setting the label to `null` (Please keep in mind that the `label` property on root needs to be set to `null` as well, otherwise the fallback applies). This change is caused by issue #2347. -* The `useBranchName` magic string has been removed. Instead use `{BranchName}` for `label`. -* The `BranchPrefixToTrim` configuration property has been removed. `RegularExpression` is now used to capture named groups instead. - * Default `RegularExpression` for feature branches is changed from `^features?[/-]` to `^features?[/-](?.+)` to support using `{BranchName}` out-of-the-box - * Default `RegularExpression` for unknown branches is changed from `.*` to `(?.+)` to support using `{BranchName}` out-of-the-box -* The `Mainline` mode and the related implementation has been removed completely. The new `Mainline` version strategy should be used instead. -* The `Mainline` version strategy doesn't support downgrading the increment for calculating the next version. This is the case if e.g. a bump messages has been defined which is lower than the branch increment. -* The branch related property `is-mainline` in the configuration system has been renamed to `is-main-branch` -* The versioning mode has been renamed to deployment mode and consists of following values: - * ManualDeployment (previously ContinuousDelivery) - * ContinuousDelivery (previously ContinuousDeployment) - * ContinuousDeployment (new) -* At the configuration root level, a new array called `strategies` has been introduced, which can consist of on or more following values: - * ConfiguredNextVersion - * MergeMessage - * TaggedCommit - * TrackReleaseBranches - * VersionInBranchName - * Mainline -* The initialization wizard has been removed. -* On the `develop`, `release` and `hotfix` branch the introduced branch related property `prevent-increment.when-current-commit-tagged` has been set to `false` to get the incremented instead of the tagged semantic version. -* When setting the "ignore commits before" parameter to a future value, an exception will occur if no commits are found on the current branch. This behavior mimics that of an empty repository. -* On the `GitFlow` workflow the increment property has been changed: - * in branch `release` from `None` to `Minor` and - * in branch `hotfix` from `None` to `Patch` -* On the `GitHubFlow` workflow the increment property has been changed in branch `release` from `None` to `Patch`. -* When creating a branch with name `hotfix/next` (by using the `GitFlow` workflow) or `release/next` (by the `GitHubFlow` workflow) the resulting version will yield to a patched version per default. -* If you have a tag `1.0.0` on `main` and branch from `main` to `release/1.0.1` then the next version number will be `1.1.0` when using the `GitFlow` workflow. This behavior is expected (but different compared to the `GitHubFlow` workflow) because on the `GitFlow` workflow you have an addition branch configuration with name hotfix where `is-release-branch` is set to `true`. That means if you want `1.0.1` as a next version you need to branch to `hotfix/1.0.1` or `hotfix/next`. On the other hand if you use the `GitHubFlow` workflow the next version number will be `1.0.1` because the increment on the `release` branch is set to `Patch`. + +* When overriding the configuration with e.g. GitVersion.yaml the software distinguishes between properties who are not existent and properties who are `null`. This is especially important if the user wants to define branch related configuration which are marked with `increment` strategy `Inherit`. +* Following root configuration properties have been removed: + * continuous-delivery-fallback-tag +* A new branch related property with name `track-merge-message` has been introduced. 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. In this scenario the merge message will be interpreted as a next version `1.0.0` when `track-merge-message` is set to `true` otherwise `0.0.1`. +* The pre-release tags are only considered when they are matching with the label name of the branch. This has an effect on the way how the `CommitCountSource` will be determined. +* The process of increasing the version with bump message when `CommitMessageIncrementing` is enabled and increment strategy is `None` has been changed. +* A new configuration property with name `version-in-branch-pattern` has been introduced. This setting only applies on branches where the option `is-release-branch` is set to `true`. Please notice that the branch name needs to be defined after the version number by default (instead of `support/lts-2.0.0` please name the branch like `support/2.0.0-lts`). +* The `is-release-branch` property of the `hotfix` branch setting has been changed from `false` to `true`. If present the hotfix number will be considered now by default. +* In the GitHub and the Git Flow workflows the `label` property is by default set to an empty string on the `main` branch. This yields to a pre-release version on `main` with an empty tag. Instead of for instance `1.0.1+46` GitVersion generates the full semantic version `1.0.1-46` instead. This behavior can be changed to generate only stable versions (no pre-release version) with setting the label to `null` (Please keep in mind that the `label` property on root needs to be set to `null` as well, otherwise the fallback applies). This change is caused by issue #2347. +* The `useBranchName` magic string has been removed. Instead use `{BranchName}` for `label`. +* The `BranchPrefixToTrim` configuration property has been removed. `RegularExpression` is now used to capture named groups instead. + * Default `RegularExpression` for feature branches is changed from `^features?[/-]` to `^features?[/-](?.+)` to support using `{BranchName}` out-of-the-box + * Default `RegularExpression` for unknown branches is changed from `.*` to `(?.+)` to support using `{BranchName}` out-of-the-box +* The `Mainline` mode and the related implementation has been removed completely. The new `Mainline` version strategy should be used instead. +* The `Mainline` version strategy doesn't support downgrading the increment for calculating the next version. This is the case if e.g. a bump messages has been defined which is lower than the branch increment. +* The branch related property `is-mainline` in the configuration system has been renamed to `is-main-branch` +* The versioning mode has been renamed to deployment mode and consists of following values: + * ManualDeployment (previously ContinuousDelivery) + * ContinuousDelivery (previously ContinuousDeployment) + * ContinuousDeployment (new) +* At the configuration root level, a new array called `strategies` has been introduced, which can consist of on or more following values: + * ConfiguredNextVersion + * MergeMessage + * TaggedCommit + * TrackReleaseBranches + * VersionInBranchName + * Mainline +* The initialization wizard has been removed. +* On the `develop`, `release` and `hotfix` branch the introduced branch related property `prevent-increment.when-current-commit-tagged` has been set to `false` to get the incremented instead of the tagged semantic version. +* When setting the "ignore commits before" parameter to a future value, an exception will occur if no commits are found on the current branch. This behavior mimics that of an empty repository. +* On the `GitFlow` workflow the increment property has been changed: + * in branch `release` from `None` to `Minor` and + * in branch `hotfix` from `None` to `Patch` +* On the `GitHubFlow` workflow the increment property has been changed in branch `release` from `None` to `Patch`. +* When creating a branch with name `hotfix/next` (by using the `GitFlow` workflow) or `release/next` (by the `GitHubFlow` workflow) the resulting version will yield to a patched version per default. +* If you have a tag `1.0.0` on `main` and branch from `main` to `release/1.0.1` then the next version number will be `1.1.0` when using the `GitFlow` workflow. This behavior is expected (but different compared to the `GitHubFlow` workflow) because on the `GitFlow` workflow you have an addition branch configuration with name hotfix where `is-release-branch` is set to `true`. That means if you want `1.0.1` as a next version you need to branch to `hotfix/1.0.1` or `hotfix/next`. On the other hand if you use the `GitHubFlow` workflow the next version number will be `1.0.1` because the increment on the `release` branch is set to `Patch`. ## v5.0.0 -* Version numbers in branches other than `release` branches are no longer +* Version numbers in branches other than `release` branches are no longer considered as a version source by default. Implemented in [#1541][pr-1541]. -* [#1581][pr-1581] folds `GitTools.Core` back into GitVersion to make +* [#1581][pr-1581] folds `GitTools.Core` back into GitVersion to make maintaining GitVersion easier. ## v4.0.0 @@ -78,35 +85,35 @@ When using GitFlow, a few things have changed. Hopefully the new settings just work for you -* `develop` has pre-release tag of `alpha` now, not unstable. -* `develop` will bump as soon as a `release` branch is created. -* Look at the [GitFlow examples][gitflow] for details of how it works now. +* `develop` has pre-release tag of `alpha` now, not unstable. +* `develop` will bump as soon as a `release` branch is created. +* Look at the [GitFlow examples][gitflow] for details of how it works now. ### Configuration Changes -* `GitVersionConfig.yaml` is deprecated in favor of `GitVersion.yml`. -* Regular expressions are no longer used as keys in branch config - * We have named branches, and introduced a `regex` config which you can +* `GitVersionConfig.yaml` is deprecated in favor of `GitVersion.yml`. +* Regular expressions are no longer used as keys in branch config + * We have named branches, and introduced a `regex` config which you can override. - * The default keys are: `master`, `develop`, `feature`, `release`, `pull-request`, + * The default keys are: `master`, `develop`, `feature`, `release`, `pull-request`, `hotfix` and `support` - * Just run `GitVersion.exe` in your project directory and it will tell you + * Just run `GitVersion.exe` in your project directory and it will tell you what to change your config keys to - * For example, `dev(elop)?(ment)?$` is now just `develop`, we suggest not + * For example, `dev(elop)?(ment)?$` is now just `develop`, we suggest not overring regular expressions unless you really want to use a different convention. -* `source-branches` added as a configuration option for branches, it helps +* `source-branches` added as a configuration option for branches, it helps GitVersion pick the correct source branch ## v3.0.0 -* NextVersion.txt has been deprecated, only `GitVersionConfig.yaml` is supported -* `AssemblyFileSemVer` variable removed, `AssemblyVersioningScheme` configuration +* NextVersion.txt has been deprecated, only `GitVersionConfig.yaml` is supported +* `AssemblyFileSemVer` variable removed, `AssemblyVersioningScheme` configuration value makes this variable obsolete -* Variables `ClassicVersion` and `ClassicVersionWithTag` removed -* MSBuild task arguments (`AssemblyVersioningScheme`, `DevelopBranchTag`, +* Variables `ClassicVersion` and `ClassicVersionWithTag` removed +* MSBuild task arguments (`AssemblyVersioningScheme`, `DevelopBranchTag`, `ReleaseBranchTag`, `TagPrefix`, `NextVersion`) have been removed, use `GitVersionConfig.yaml` instead -* GitVersionTask's `ReleaseDateAttribute` no longer exists +* GitVersionTask's `ReleaseDateAttribute` no longer exists [gitflow]: https://gitversion.net/docs/learn/branching-strategies/gitflow-examples_complete [pr-1541]: https://github.com/GitTools/GitVersion/pull/1541 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index da08a4f88a..fa2ab0c87e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,10 +2,10 @@ We love contributions to get started contributing you might need: -* [Get started with git](https://rogerdudler.github.io/git-guide) -* [How to create a pull request](https://help.github.com/articles/using-pull-requests) -* [An issue to work on](https://github.com/GitTools/GitVersion/labels/up-for-grabs) - We are on [Up for grabs](https://up-for-grabs.net/), our up for grabs issues are tagged `up-for-grabs` -* An understanding of our [architecture](https://gitversion.net/docs/learn/how-it-works#architecture) and how [we write tests](#writing-tests) +* [Get started with git](https://rogerdudler.github.io/git-guide) +* [How to create a pull request](https://help.github.com/articles/using-pull-requests) +* [An issue to work on](https://github.com/GitTools/GitVersion/labels/up-for-grabs) - We are on [Up for grabs](https://up-for-grabs.net/), our up for grabs issues are tagged `up-for-grabs` +* An understanding of our [architecture](https://gitversion.net/docs/learn/how-it-works#architecture) and how [we write tests](#writing-tests) Once you know how to create a pull request and have an issue to work on, just post a comment saying you will work on it. If you end up not being able to complete the task, please post another comment so others can pick it up. @@ -14,9 +14,9 @@ Issues are also welcome, [failing tests](#writing-tests) are even more welcome. ## Contribution Guidelines -* Try to use feature branches rather than developing on main. -* Please include tests covering the change. -* The documentation is stored in the repository under the [`docs`](docs) folder. +* Try to use feature branches rather than developing on main. +* Please include tests covering the change. +* The documentation is stored in the repository under the [`docs`](docs) folder. Have a look at the [documentation readme file](docs/readme.md) for guidance on how to improve the documentation and please include documentation updates with your PR. @@ -50,6 +50,7 @@ var configurationBuilder = GitFlowConfigurationBuilder.New; We can then customize the configuration by chaining methods of the builder. At the end we build the configuration. For example: + ```csharp var configuration = configurationBuilder .WithDeploymentMode(DeploymentMode.ContinuousDeployment) @@ -61,9 +62,9 @@ var configuration = configurationBuilder We have a few fixtures for different scenarios. -* `EmptyRepositoryFixture` - Gives you an empty git repo to start with -* `RemoteRepositoryFixture` - A local repo tracking a test remote repository. The remote repo is available through the `Repository` property, the local is accessible via `LocalRepository` -* `BaseGitFlowRepositoryFixture` - A repo setup for GitFlow (has a develop branch checked out ready to go) +* `EmptyRepositoryFixture` - Gives you an empty git repo to start with +* `RemoteRepositoryFixture` - A local repo tracking a test remote repository. The remote repo is available through the `Repository` property, the local is accessible via `LocalRepository` +* `BaseGitFlowRepositoryFixture` - A repo setup for GitFlow (has a develop branch checked out ready to go) You can use a fixture by just `using` it. Like this @@ -97,18 +98,18 @@ Even better include the fix, but a failing test is a great start We use Cake for our build and deployment process. The way the release process is setup is: -1. We build releasable artifacts with GitHub Actions -2. We create a milestone for the release if it's not already created. Our milestones are named using the semver. +1. We build releasable artifacts with GitHub Actions +2. We create a milestone for the release if it's not already created. Our milestones are named using the semver. For example `5.12.0` or `6.0.0-beta.2` -3. We move all the closed issues and closed pull requests that are going to be included in the release to the milestone. -4. We check that all the issues and pull requests that are going to be included in the release have a label assigned, +3. We move all the closed issues and closed pull requests that are going to be included in the release to the milestone. +4. We check that all the issues and pull requests that are going to be included in the release have a label assigned, otherwise it will fail the release. -5. We create a release in the GitHub UI, and create a tag and name it using the milestone name. For example `5.12.0` or `6.0.0-beta.2` -6. We specify if the release is a pre-release or latest release in the GitHub UI. -7. We publish the release. -8. The GitHub Actions will create a GitHub release and publish the artifacts to NuGet, Chocolatey, Docker, Homebrew +5. We create a release in the GitHub UI, and create a tag and name it using the milestone name. For example `5.12.0` or `6.0.0-beta.2` +6. We specify if the release is a pre-release or latest release in the GitHub UI. +7. We publish the release. +8. The GitHub Actions will create a GitHub release and publish the artifacts to NuGet, Chocolatey, Docker, Homebrew and other distribution channels. -9. The issues and pull requests will get updated with message specifying in which release it was included. +9. The issues and pull requests will get updated with message specifying in which release it was included. ## Code Style diff --git a/README.md b/README.md index 684d8ee417..3627b83c90 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -![GitVersion – From git log to SemVer in no time][banner] +# ![GitVersion – From git log to SemVer in no time][banner] Versioning when using Git, solved. GitVersion looks at your git history and works out the [Semantic Version][semver] of the commit being built. @@ -27,13 +27,13 @@ GitVersion works on Windows, Linux, and Mac. ## Quick Links -* [Documentation][docs] -* [Contributing][contribute] -* [Why GitVersion][why] -* [Usage][usage] -* [How it works][how] -* [FAQ][faq] -* [Who is using GitVersion][who] +* [Documentation][docs] +* [Contributing][contribute] +* [Why GitVersion][why] +* [Usage][usage] +* [How it works][how] +* [FAQ][faq] +* [Who is using GitVersion][who] ## GitVersion in action! @@ -41,8 +41,8 @@ GitVersion works on Windows, Linux, and Mac. You are seeing: -* Pull requests being built as pre-release builds -* A branch called `release-1.0.0` producing beta v1 packages +* Pull requests being built as pre-release builds +* A branch called `release-1.0.0` producing beta v1 packages ## Icon diff --git a/SECURITY.md b/SECURITY.md index 6e0e279f39..6e07e80a06 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -17,13 +17,13 @@ You should receive a response within 24 hours. If for some reason you do not, pl Please include the requested information listed below (as much as you can provide) to help us better understand the nature and scope of the possible issue: -* Type of issue (e.g. buffer overflow, SQL injection, cross-site scripting, etc.) -* Full paths of source file(s) related to the manifestation of the issue -* The location of the affected source code (tag/branch/commit or direct URL) -* Any special configuration required to reproduce the issue -* Step-by-step instructions to reproduce the issue -* Proof-of-concept or exploit code (if possible) -* Impact of the issue, including how an attacker might exploit the issue +* Type of issue (e.g. buffer overflow, SQL injection, cross-site scripting, etc.) +* Full paths of source file(s) related to the manifestation of the issue +* The location of the affected source code (tag/branch/commit or direct URL) +* Any special configuration required to reproduce the issue +* Step-by-step instructions to reproduce the issue +* Proof-of-concept or exploit code (if possible) +* Impact of the issue, including how an attacker might exploit the issue This information will help us triage your report more quickly. diff --git a/build/nuspec/README.md b/build/nuspec/README.md index 92ee4c6227..9ab06f932c 100644 --- a/build/nuspec/README.md +++ b/build/nuspec/README.md @@ -16,13 +16,13 @@ GitVersion works on Windows, Linux, and Mac. ## Quick Links -* [Documentation][docs] -* [Contributing][contribute] -* [Why GitVersion][why] -* [Usage][usage] -* [How it works][how] -* [FAQ][faq] -* [Who is using GitVersion][who] +* [Documentation][docs] +* [Contributing][contribute] +* [Why GitVersion][why] +* [Usage][usage] +* [How it works][how] +* [FAQ][faq] +* [Who is using GitVersion][who] ## GitVersion in action! @@ -30,8 +30,8 @@ GitVersion works on Windows, Linux, and Mac. You are seeing: -* Pull requests being built as pre-release builds -* A branch called `release-1.0.0` producing beta v1 packages +* Pull requests being built as pre-release builds +* A branch called `release-1.0.0` producing beta v1 packages ## Icon @@ -46,8 +46,6 @@ from The Noun Project. [gvt]: https://www.nuget.org/packages/GitVersion.MsBuild [gvt-badge]: https://img.shields.io/nuget/v/GitVersion.MsBuild.svg?logo=nuget [gitversiontask]: https://www.nuget.org/packages/GitVersionTask/ -[gvcl]: https://www.nuget.org/packages/GitVersion.CommandLine -[gvcl-badge]: https://img.shields.io/nuget/v/GitVersion.CommandLine.svg?logo=nuget [gvgt]: https://www.nuget.org/packages/GitVersion.Tool [gvgt-badge]: https://img.shields.io/nuget/v/GitVersion.Tool.svg?logo=nuget [contribute]: https://github.com/GitTools/GitVersion/blob/main/CONTRIBUTING.md diff --git a/docs/input/docs/learn/branching-strategies/contribute-examples.md b/docs/input/docs/learn/branching-strategies/contribute-examples.md index c162dfe85e..3651bc91c6 100644 --- a/docs/input/docs/learn/branching-strategies/contribute-examples.md +++ b/docs/input/docs/learn/branching-strategies/contribute-examples.md @@ -9,8 +9,8 @@ The examples are generated by GitVersion tests, there are a number of services which will then turn the sequence diagram text into an image to use in the docs. Here are some links which could be useful -* [PlantUML Sequence Diagrams](https://www.plantuml.com/sequence.html) -* [PlantText Online editor](https://www.planttext.com) +* [PlantUML Sequence Diagrams](https://www.plantuml.com/sequence.html) +* [PlantText Online editor](https://www.planttext.com) The tests are quite simple. Using the methods on the `fixture` itself will record that action in the sequence diagram. If you do not want the action diff --git a/docs/input/docs/learn/branching-strategies/gitflow/index.md b/docs/input/docs/learn/branching-strategies/gitflow/index.md index 4a0895e419..dbb5688c1b 100644 --- a/docs/input/docs/learn/branching-strategies/gitflow/index.md +++ b/docs/input/docs/learn/branching-strategies/gitflow/index.md @@ -10,20 +10,20 @@ SemVer compatible versions from this structure. ## Assumptions: -* Using [GitFlow branching model](https://nvie.com/git-model/) which always has a +* Using [GitFlow branching model](https://nvie.com/git-model/) which always has a main and a develop branch -* Following [Semantic Versioning](https://semver.org/) -* Planned releases (bumps in major or minor) are done on release branches +* Following [Semantic Versioning](https://semver.org/) +* Planned releases (bumps in major or minor) are done on release branches prefixed with release-. Eg: release-4.1 (or release-4.1.0) -* Hotfixes are prefixed with hotfix- Eg. hotfix-4.0.4 -* The original [GitFlow model](https://nvie.com/posts/a-successful-git-branching-model/) +* Hotfixes are prefixed with hotfix- Eg. hotfix-4.0.4 +* The original [GitFlow model](https://nvie.com/posts/a-successful-git-branching-model/) specifies branches with a "-" separator while the [git flow extensions](https://github.com/CJ-Systems/gitflow-cjs) default to a "/" separator. Either work with GitVersion. -* Tags are used on the main branch and reflects the SemVer of each stable +* Tags are used on the main branch and reflects the SemVer of each stable release eg 3.3.8 , 4.0.0, etc -* Tags can also be used to override versions while we transition repositories +* Tags can also be used to override versions while we transition repositories over to GitVersion -* Using a build server with multi-branch building enabled eg TeamCity 8 +* Using a build server with multi-branch building enabled eg TeamCity 8 ## How Branches are handled @@ -31,8 +31,8 @@ The descriptions of how commits and branches are versioned can be considered a type of pseudopod. With that in mind there are a few common "variables" that we will refer to: -* `targetBranch` => the branch we are targeting -* `targetCommit` => the commit we are targeting on `targetbranch` +* `targetBranch` => the branch we are targeting +* `targetCommit` => the commit we are targeting on `targetbranch` ### Main branch @@ -44,15 +44,15 @@ If we try to build from a commit that is no merge and no tag then assume `0.1.0` `mergeVersion` => the SemVer extracted from `targetCommit.Message` -* major: `mergeVersion.Major` -* minor: `mergeVersion.Minor` -* patch: `mergeVersion.Patch` -* pre-release: 0 (perhaps count ahead commits later) -* stability: final +* major: `mergeVersion.Major` +* minor: `mergeVersion.Minor` +* patch: `mergeVersion.Patch` +* pre-release: 0 (perhaps count ahead commits later) +* stability: final Optional Tags (only when transitioning existing repository): -* TagOnHeadCommit.Name={semver} => overrides the version to be {semver} +* TagOnHeadCommit.Name={semver} => overrides the version to be {semver} Long version: @@ -68,10 +68,10 @@ Long version: `main` that is older than the `targetCommitDate` `mainMergeVersion` => the SemVer extracted from `mainVersionCommit.Message` -* major: `mainMergeVersion.Major` -* minor: `mainMergeVersion.Minor + 1` (0 if the override above is used) -* patch: 0 -* pre-release: `alpha.{n}` where n = how many commits `develop` is in front of +* major: `mainMergeVersion.Major` +* minor: `mainMergeVersion.Minor + 1` (0 if the override above is used) +* patch: 0 +* pre-release: `alpha.{n}` where n = how many commits `develop` is in front of `mainVersionCommit.Date` ('0' padded to 4 characters) Long version: @@ -87,10 +87,10 @@ Named: `hotfix-{versionNumber}` eg `hotfix-1.2` `branchVersion` => the SemVer extracted from `targetBranch.Name` -* major: `mergeVersion.Major` -* minor: `mergeVersion.Minor` -* patch: `mergeVersion.Patch` -* pre-release: `beta{n}` where n = number of commits on branch ('0' padded to +* major: `mergeVersion.Major` +* minor: `mergeVersion.Minor` +* patch: `mergeVersion.Patch` +* pre-release: `beta{n}` where n = number of commits on branch ('0' padded to 4 characters) Long version: @@ -102,9 +102,9 @@ Long version: ### Release branches -* May branch off from: develop -* Must merge back into: develop and main -* Branch naming convention: `release-{n}` eg `release-1.2` +* May branch off from: develop +* Must merge back into: develop and main +* Branch naming convention: `release-{n}` eg `release-1.2` `releaseVersion` => the SemVer extracted from `targetBranch.Name` `releaseTag` => the first version tag placed on the branch. Note that at least @@ -112,10 +112,10 @@ one version tag is required on the branch. The recommended initial tag is `{releaseVersion}.0-alpha1`. So for a branch named `release-1.2` the recommended tag would be `1.2.0-alpha1` -* major: `mergeVersion.Major` -* minor: `mergeVersion.Minor` -* patch: 0 -* pre-release: `{releaseTag.preRelease}.{n}` where n = 1 + the number of commits +* major: `mergeVersion.Major` +* minor: `mergeVersion.Minor` +* patch: 0 +* pre-release: `{releaseTag.preRelease}.{n}` where n = 1 + the number of commits since `releaseTag`. So on a branch named `release-1.2` with a tag `1.2.0-alpha1` and 4 commits after @@ -139,10 +139,10 @@ Branch naming convention: anything except `main`, `develop`, `release-{n}`, or TODO: feature branches cannot start with a SemVer. to stop people from create branches named like "4.0.3" -* major: `mainMergeVersion.Major` -* minor: `mainMergeVersion.Minor + 1` (0 if the override above is used) -* patch: 0 -* pre-release: `alpha.feature-{n}` where n = First 8 characters of the commit +* major: `mainMergeVersion.Major` +* minor: `mainMergeVersion.Minor + 1` (0 if the override above is used) +* patch: 0 +* pre-release: `alpha.feature-{n}` where n = First 8 characters of the commit SHA of the first commit Long version: @@ -159,10 +159,10 @@ Must merge back into: `develop` Branch naming convention: anything except `main`, `develop`, `release-{n}`, or `hotfix-{n}`. Canonical branch name contains `/pull/`. -* major: `mainMergeVersion.Major` -* minor: `mainMergeVersion.Minor + 1` (0 if the override above is used) -* patch: 0 -* pre-release: `alpha.pull{n}` where n = the pull request number ('0' padded to +* major: `mainMergeVersion.Major` +* minor: `mainMergeVersion.Minor + 1` (0 if the override above is used) +* patch: 0 +* pre-release: `alpha.pull{n}` where n = the pull request number ('0' padded to 4 characters) ## Nightly Builds diff --git a/docs/input/docs/learn/branching-strategies/githubflow/index.md b/docs/input/docs/learn/branching-strategies/githubflow/index.md index d683b2d906..89ae283bfa 100644 --- a/docs/input/docs/learn/branching-strategies/githubflow/index.md +++ b/docs/input/docs/learn/branching-strategies/githubflow/index.md @@ -11,19 +11,19 @@ are much better off with a simpler workflow. GitHubFlow is in a nutshell: -1. Update main to latest [upstream](/docs/learn/git-setup#upstream) code -2. Create a feature branch `git checkout -b myFeatureBranch` -3. Do the feature/work -4. Push feature branch to [origin](/docs/learn/git-setup#origin) -5. Create pull request from origin/ -> upstream/main -6. Review, fix raised comments, merge your PR or even better, get someone else to. +1. Update main to latest [upstream](/docs/learn/git-setup#upstream) code +2. Create a feature branch `git checkout -b myFeatureBranch` +3. Do the feature/work +4. Push feature branch to [origin](/docs/learn/git-setup#origin) +5. Create pull request from origin/ -> upstream/main +6. Review, fix raised comments, merge your PR or even better, get someone else to. The main rule of GitHub Flow is that main should _always_ be deployable. GitHub Flow allows and encourages [continuous delivery](/docs/reference/modes/continuous-delivery). ## Resources -* [GitHubFlow guide by GitHub](https://docs.github.com/en/get-started/quickstart/github-flow#introduction) -* [GitHubFlow original blog post](https://scottchacon.com/2011/08/31/github-flow) -* [Phil Haack's (haacked) GitHubFlow aliases](https://haacked.com/archive/2014/07/28/github-flow-aliases/) -* [GitHubFlow vs GitFlow](https://lucamezzalira.com/2014/03/10/git-flow-vs-github-flow/) +* [GitHubFlow guide by GitHub](https://docs.github.com/en/get-started/quickstart/github-flow#introduction) +* [GitHubFlow original blog post](https://scottchacon.com/2011/08/31/github-flow) +* [Phil Haack's (haacked) GitHubFlow aliases](https://haacked.com/archive/2014/07/28/github-flow-aliases/) +* [GitHubFlow vs GitFlow](https://lucamezzalira.com/2014/03/10/git-flow-vs-github-flow/) diff --git a/docs/input/docs/learn/branching-strategies/overview.md b/docs/input/docs/learn/branching-strategies/overview.md index aae1372e90..b5053214b3 100644 --- a/docs/input/docs/learn/branching-strategies/overview.md +++ b/docs/input/docs/learn/branching-strategies/overview.md @@ -26,32 +26,32 @@ As mentioned above the GitVersion docs cover [GitHubFlow][githubflow] and GitHubFlow is a simple and powerful branching strategy. It is what GitHub uses and the branching strategy most open source projects use. -* [Mainline development][mainline] on `main`. -* Work on [feature branches][feature-branches], merge into `main` via a [pull +* [Mainline development][mainline] on `main`. +* Work on [feature branches][feature-branches], merge into `main` via a [pull request][pull-request]. -* Works well for [continuous delivery][continuous-delivery]. -* Does not have a way to manage/maintain old releases. -* Only allows working on a single release at a time. +* Works well for [continuous delivery][continuous-delivery]. +* Does not have a way to manage/maintain old releases. +* Only allows working on a single release at a time. ### Git Flow GitFlow is a more complex and complete branching strategy. It also gives much more control over when features and code is released. -* Development on `develop` branch. -* `main` only contains _released_ code. -* Supports maintaining old releases (like nServiceBus, they support the last 3 +* Development on `develop` branch. +* `main` only contains _released_ code. +* Supports maintaining old releases (like nServiceBus, they support the last 3 major versions with bug fixes and security updates). -* Supports development on multiple releases at one time. +* Supports development on multiple releases at one time. ## Choosing a branching strategy There are a few reasons you would pick GitFlow over GitHubFlow, they are: -1. You need to support multiple major versions at the same time. -2. You need to work on multiple releases at the same time. +1. You need to support multiple major versions at the same time. +2. You need to work on multiple releases at the same time. -* For example a new feature which will go in the next major version, while bug +* For example a new feature which will go in the next major version, while bug fixes/smaller features are still going into the current release But if you do not have a good reason to go with GitFlow, then start with diff --git a/docs/input/docs/learn/dynamic-repositories.md b/docs/input/docs/learn/dynamic-repositories.md index 0ba9bf49cb..848ac16391 100644 --- a/docs/input/docs/learn/dynamic-repositories.md +++ b/docs/input/docs/learn/dynamic-repositories.md @@ -31,11 +31,11 @@ will assume there is already a ".git" folder present, and it will use it. To tell GitVersion.exe to obtain the repository on the fly, you need to call `GitVersion.exe` with the following arguments: -* `/url [the url of your git repo]` -* `/u [authentication username]` -* `/p [authentication password]` -* `/b [branch name]` -* `/c [commit id]` +* `/url [the url of your git repo]` +* `/u [authentication username]` +* `/p [authentication password]` +* `/b [branch name]` +* `/c [commit id]` Please note that these arguments are described when calling `GitVersion.exe /?`. diff --git a/docs/input/docs/learn/how-it-works.md b/docs/input/docs/learn/how-it-works.md index 6c3ee2ae1a..36ba942451 100644 --- a/docs/input/docs/learn/how-it-works.md +++ b/docs/input/docs/learn/how-it-works.md @@ -16,12 +16,12 @@ it _much_ more predictable and easier to diagnose when odd things are happening. GitVersion has three distinct steps for calculating versions in v3. -1. If the current commit is tagged, the tag is used and build metadata +1. If the current commit is tagged, the tag is used and build metadata (excluding commit count) is added. The other two steps will not execute. -2. A set of strategies are evaluated to decide on the base version and some +2. A set of strategies are evaluated to decide on the base version and some metadata about that version. These strategies include HighestReachableTag, NextVersionInConfig, MergedBranchWithVersion, VersionInBranchName etc. -3. The highest base version is selected, using that base version as the new +3. The highest base version is selected, using that base version as the new version is calculated. Visually it looks something like this: @@ -39,30 +39,30 @@ simply to show what happens if the check is true. Currently we have the following strategies: -* `HighestTagBaseVersionStrategy` - Finds the highest reachable tag from the +* `HighestTagBaseVersionStrategy` - Finds the highest reachable tag from the current branch -* `VersionInBranchBaseVersionStrategy` - Extracts version information from the +* `VersionInBranchBaseVersionStrategy` - Extracts version information from the branch name (e.g., `release/3.0.0` will find `3.0.0`) -* `ConfigNextVersionBaseVersionStrategy` - Returns the version from the +* `ConfigNextVersionBaseVersionStrategy` - Returns the version from the GitVersion.yaml file -* `MergeMessageBaseVersionStrategy` - Finds version numbers from merge messages +* `MergeMessageBaseVersionStrategy` - Finds version numbers from merge messages (e.g., `Merge 'release/3.0.0' into 'main'` will return `3.0.0`) -* `FallbackBaseVersionStrategy` - Always returns 0.0.0 and will be used for - calculating the next version which is dependent on the increment strategy of - the effected branch (e.g. on main the next version is 0.0.1 or on develop it is 0.1.0) +* `FallbackBaseVersionStrategy` - Always returns 0.0.0 and will be used for + calculating the next version which is dependent on the increment strategy of + the effected branch (e.g. on main the next version is 0.0.1 or on develop it is 0.1.0) Each strategy needs to return an instance of `BaseVersion` which has the following properties: -* `Source` - Description of the source (e.g., `Merge message 'Merge 'release/3.0.0' into 'main'`) -* `ShouldIncrement` - Some strategies should have the version incremented, +* `Source` - Description of the source (e.g., `Merge message 'Merge 'release/3.0.0' into 'main'`) +* `ShouldIncrement` - Some strategies should have the version incremented, others do not (e.g., `ConfigNextVersionBaseVersionStrategy` returns false, `HighestTagBaseVersionStrategy` returns true) -* `SemanticVersion` - SemVer of the base version strategy -* `BaseVersionSource` - SHA hash of the source. Commits will be counted from +* `SemanticVersion` - SemVer of the base version strategy +* `BaseVersionSource` - SHA hash of the source. Commits will be counted from this hash. Can be null (e.g., `ConfigNextVersionBaseVersionStrategy` returns null). -* `BranchNameOverride` - When `useBranchName` or `{BranchName}` is used in the +* `BranchNameOverride` - When `useBranchName` or `{BranchName}` is used in the tag configuration, this allows the branch name to be changed by a base version. `VersionInBranchBaseVersionStrategy` uses this to strip out anything before the first `-` or `/.` so `foo` ends up being evaluated as `foo`. If in doubt, just diff --git a/docs/input/docs/learn/intro-to-semver.md b/docs/input/docs/learn/intro-to-semver.md index 179010169c..43a73646bf 100644 --- a/docs/input/docs/learn/intro-to-semver.md +++ b/docs/input/docs/learn/intro-to-semver.md @@ -16,12 +16,12 @@ Version Promiscuity is the opposite problem, **JsonLibrary** releases _v1.1.0_ w SemVer introduces conventions about breaking changes into our version numbers so we can safely upgrade dependencies without fear of unexpected, breaking changes while still allowing us to upgrade downstream libraries to get new features and bug fixes. The convention is quite simple: -* `{major}.{minor}.{patch}-{tag}+{buildmetadata}` -* `{major}` is only incremented if the release has breaking changes (includes bug fixes which have breaking behavioural changes -* `{minor}` is incremented if the release has new non-breaking features -* `{patch}` is incremented if the release only contains non-breaking bug fixes -* `{tag}` is optional and denotes a pre-release of the version preceding -* `{buildmetadata}` is optional and contains additional information about the version, but **does not affect** the semantic version preceding it. +* `{major}.{minor}.{patch}-{tag}+{buildmetadata}` +* `{major}` is only incremented if the release has breaking changes (includes bug fixes which have breaking behavioural changes +* `{minor}` is incremented if the release has new non-breaking features +* `{patch}` is incremented if the release only contains non-breaking bug fixes +* `{tag}` is optional and denotes a pre-release of the version preceding +* `{buildmetadata}` is optional and contains additional information about the version, but **does not affect** the semantic version preceding it. Only one number should be incremented per release, and all lower parts should be reset to 0 (if `{major}` is incremented, then `{minor}` and `{patch}` should become 0). diff --git a/docs/input/docs/learn/who.md b/docs/input/docs/learn/who.md index bbcaba18a8..ace607d739 100644 --- a/docs/input/docs/learn/who.md +++ b/docs/input/docs/learn/who.md @@ -8,19 +8,19 @@ Various people are actively using GitVersion, and taking advantage of the automatic generation of their version numbers. Here is a list of applications that we know about today. -* [Catel](https://github.com/catel/catel) -* [ChocolateyGUI](https://github.com/chocolatey/ChocolateyGUI) -* [GitLink](https://github.com/GitTools/GitLink) -* [OctopusDeploy](https://github.com/OctopusDeploy) -* [NUKE](https://nuke.build) -* [Orc.\* packages](https://github.com/wildgums?query=orc) -* [Orchestra](https://github.com/wildgums/orchestra) -* [Shouldly](https://github.com/shouldly/shouldly) -* [Akavache](https://github.com/akavache/akavache) -* [Splat](https://github.com/paulcbetts/splat) -* [ReactiveUI](https://github.com/reactiveui/reactiveui) -* [Uno Platform](https://platform.uno/) -* [Fluent Assertions](https://fluentassertions.com) +* [Catel](https://github.com/catel/catel) +* [ChocolateyGUI](https://github.com/chocolatey/ChocolateyGUI) +* [GitLink](https://github.com/GitTools/GitLink) +* [OctopusDeploy](https://github.com/OctopusDeploy) +* [NUKE](https://nuke.build) +* [Orc.\* packages](https://github.com/wildgums?query=orc) +* [Orchestra](https://github.com/wildgums/orchestra) +* [Shouldly](https://github.com/shouldly/shouldly) +* [Akavache](https://github.com/akavache/akavache) +* [Splat](https://github.com/paulcbetts/splat) +* [ReactiveUI](https://github.com/reactiveui/reactiveui) +* [Uno Platform](https://platform.uno/) +* [Fluent Assertions](https://fluentassertions.com) If you are using GitVersion in your projects, and you are not listed above, please feel free to add a link to your project. diff --git a/docs/input/docs/learn/why.md b/docs/input/docs/learn/why.md index 421db61eee..a87ef0cc3a 100644 --- a/docs/input/docs/learn/why.md +++ b/docs/input/docs/learn/why.md @@ -11,28 +11,28 @@ transportable between projects. It solves: -* Rebuilding tags always produces the same version -* Not having to rebuild to increment versions -* Not duplicating version information in multiple places (branch release/2.0.0 +* Rebuilding tags always produces the same version +* Not having to rebuild to increment versions +* Not duplicating version information in multiple places (branch release/2.0.0 already has the version in it, why do I need to change something else) -* Each branch calculates its SemVer and versions flow between branches when +* Each branch calculates its SemVer and versions flow between branches when they are merged -* Pull requests produce unique pre-release version numbers -* NuGet semver issues -* Build server integration -* Updating assembly info -* And a whole lot of edge cases you don't want to think about +* Pull requests produce unique pre-release version numbers +* NuGet semver issues +* Build server integration +* Updating assembly info +* And a whole lot of edge cases you don't want to think about ## Advantages vs other approaches ### Version.txt/Version in build script -* With version.txt/build script, after the release you need to do an additional commit to bump the version -* After tagging a release, the next build will still be the same version +* With version.txt/build script, after the release you need to do an additional commit to bump the version +* After tagging a release, the next build will still be the same version ### Build Server versioning -* Cannot have different version numbers on different branches -* Rebuilding will result in a different build number (if using an auto incrementing number in the version) -* Need to login to the build server to change version number -* Only build administrators can change the version number +* Cannot have different version numbers on different branches +* Rebuilding will result in a different build number (if using an auto incrementing number in the version) +* Need to login to the build server to change version number +* Only build administrators can change the version number diff --git a/docs/input/docs/reference/build-servers/appveyor.md b/docs/input/docs/reference/build-servers/appveyor.md index d23f0da61d..2232c49a15 100644 --- a/docs/input/docs/reference/build-servers/appveyor.md +++ b/docs/input/docs/reference/build-servers/appveyor.md @@ -8,8 +8,8 @@ RedirectFrom: docs/build-server-support/build-server/appveyor AppVeyor is the first build server which has a setup helper built into `GitVersion init`. -1. Run `GitVersion init` -2. Choose `Setup build scripts` (currently option 7, but that could change) -3. Choose `AppVeyor` -4. Follow the prompts to generate an AppVeyor.yml file which works nicely with +1. Run `GitVersion init` +2. Choose `Setup build scripts` (currently option 7, but that could change) +3. Choose `AppVeyor` +4. Follow the prompts to generate an AppVeyor.yml file which works nicely with GitVersion diff --git a/docs/input/docs/reference/build-servers/azure-devops.md b/docs/input/docs/reference/build-servers/azure-devops.md index 8439d978d6..3f548d18a4 100644 --- a/docs/input/docs/reference/build-servers/azure-devops.md +++ b/docs/input/docs/reference/build-servers/azure-devops.md @@ -17,4 +17,4 @@ without it, Azure DevOps Pipelines will perform a shallow clone, which will caus See [the Azure DevOps documentation](https://learn.microsoft.com/en-us/azure/devops/pipelines/yaml-schema/steps-checkout?view=azure-pipelines#shallow-fetch) for more information. ::: -More information can be found at [gittools/actions](https://github.com/GitTools/actions/blob/main/docs/examples/azure/gitversion/index.md). \ No newline at end of file +More information can be found at [gittools/actions](https://github.com/GitTools/actions/blob/main/docs/examples/azure/gitversion/index.md). diff --git a/docs/input/docs/reference/build-servers/bamboo.md b/docs/input/docs/reference/build-servers/bamboo.md index 71e0ad3ae1..6d0d79a263 100644 --- a/docs/input/docs/reference/build-servers/bamboo.md +++ b/docs/input/docs/reference/build-servers/bamboo.md @@ -36,6 +36,6 @@ sed -i '1d;$ d;s/ //;s/"//g;s/,//;s/:/=/' gitversion.txt **Required Properties** -* **Path to properties file**: gitversion.txt -* **Namespace**: GitVersion -* **Scope of the Variables**: Result +* **Path to properties file**: gitversion.txt +* **Namespace**: GitVersion +* **Scope of the Variables**: Result diff --git a/docs/input/docs/reference/build-servers/buildkite.md b/docs/input/docs/reference/build-servers/buildkite.md index d06e9d4aad..5bae6a9729 100644 --- a/docs/input/docs/reference/build-servers/buildkite.md +++ b/docs/input/docs/reference/build-servers/buildkite.md @@ -10,8 +10,9 @@ If you use [Buildkite][buildkite] then you will have to use GitVersion from the ## Gotchas By default Buildkite calls `git fetch` with the flags `-v --prune` which can cause issues on new build agents since branches or tags might not be available locally on the build agent when GitVersion runs. This can be fixed by altering the [Buildkite agent configuration][configuration] either by: -* Setting the environment variable `BUILDKITE_GIT_FETCH_FLAGS` to `-v --tags` -* Setting configuration value `git-fetch-flags` to `-v --tags` in your agent configuration file + +* Setting the environment variable `BUILDKITE_GIT_FETCH_FLAGS` to `-v --tags` +* Setting configuration value `git-fetch-flags` to `-v --tags` in your agent configuration file If you are running GitVersion in a docker container make sure to propagate the `BUILDKITE`, `BUILDKITE_BRANCH`, and `BUILDKITE_PULL_REQUEST` environment variables (c.f. example below). diff --git a/docs/input/docs/reference/build-servers/continua.md b/docs/input/docs/reference/build-servers/continua.md index 18f035eb04..eefe6048df 100644 --- a/docs/input/docs/reference/build-servers/continua.md +++ b/docs/input/docs/reference/build-servers/continua.md @@ -13,29 +13,29 @@ This guide assumes a few variables are present in the configuration. Note that this example uses `Catel` as repository name, but it should be replaced by the name of the repository where GitVersion is running against. -* RepositoryBranchName => $Source.Catel.BranchName$ -* RepositoryCommitId => $Source.Catel.LatestChangeset.Id$ -* RepositoryName => Catel -* RepositoryName => $Source.Catel.Path$ -* RepositoryUrl => $Source.Catel.Url$ +* RepositoryBranchName => $Source.Catel.BranchName$ +* RepositoryCommitId => $Source.Catel.LatestChangeset.Id$ +* RepositoryName => Catel +* RepositoryName => $Source.Catel.Path$ +* RepositoryUrl => $Source.Catel.Url$ It also requires a few variables which will automatically be filled by GitVersion. The example below are just a few, any of the GitVersion variables written to the output can be used. -* GitVersion_FullSemVer -* GitVersion_MajorMinorPatch -* GitVersion_NuGetVersion +* GitVersion_FullSemVer +* GitVersion_MajorMinorPatch +* GitVersion_NuGetVersion You also need to add a property collector for the agents to detect the GitVersion tool on the agents: -* Namespace => GitVersion -* Run On => Agent -* Type => Path Finder Plugin -* Property Name => Path -* Executable => GitVersion.exe -* Search paths => your installation folder (e.g. `C:\Tools\GitVersion` or if you +* Namespace => GitVersion +* Run On => Agent +* Type => Path Finder Plugin +* Property Name => Path +* Executable => GitVersion.exe +* Search paths => your installation folder (e.g. `C:\Tools\GitVersion` or if you are using Chocolatey `C:\ProgramData\chocolatey\lib\GitVersion.Portable\tools`) ## Basic Usage @@ -43,17 +43,17 @@ GitVersion tool on the agents: To run GitLink inside [Continua CI](https://www.finalbuilder.com/continua-ci), follow the steps below: -* Add a new `Execute Program` step to a stage -* In the `Execute Program` tab, set the following values: - * Executable path: $Agent.GitVersion.Path$ - * Working directory: %RepositoryPath% -* In the `Arguments` tab, set the following values: - * Arguments: /url %RepositoryUrl% /b %RepositoryBranchName% /c %RepositoryCommitId% /output buildserver -* In the `Options` tab, set the following values: - * Wait for completion: checked - * Log output: checked - * Check program exit code: checked - * Exit code must be: equal to - * Exit code: 0 +* Add a new `Execute Program` step to a stage +* In the `Execute Program` tab, set the following values: + * Executable path: $Agent.GitVersion.Path$ + * Working directory: %RepositoryPath% +* In the `Arguments` tab, set the following values: + * Arguments: /url %RepositoryUrl% /b %RepositoryBranchName% /c %RepositoryCommitId% /output buildserver +* In the `Options` tab, set the following values: + * Wait for completion: checked + * Log output: checked + * Check program exit code: checked + * Exit code must be: equal to + * Exit code: 0 Now GitVersion will automatically run and fill the `GitVersion_` variables. diff --git a/docs/input/docs/reference/build-servers/github-actions.md b/docs/input/docs/reference/build-servers/github-actions.md index 0e92cff8e6..d19e4489a5 100644 --- a/docs/input/docs/reference/build-servers/github-actions.md +++ b/docs/input/docs/reference/build-servers/github-actions.md @@ -15,4 +15,4 @@ You must disable shallow fetch by setting `fetch-depth: 0` in your `checkout` st without it, GitHub Actions might perform a shallow clone, which will cause GitVersion to display an error message. ::: -More information can be found at [gittools/actions](https://github.com/GitTools/actions/blob/main/docs/examples/github/gitversion/index.md). \ No newline at end of file +More information can be found at [gittools/actions](https://github.com/GitTools/actions/blob/main/docs/examples/github/gitversion/index.md). diff --git a/docs/input/docs/reference/build-servers/gitlab.md b/docs/input/docs/reference/build-servers/gitlab.md index a3f9acde28..9a03ac25b8 100755 --- a/docs/input/docs/reference/build-servers/gitlab.md +++ b/docs/input/docs/reference/build-servers/gitlab.md @@ -13,16 +13,16 @@ A working example of integrating GitVersion with GitLab is maintained in the pro Here is a summary of what it demonstrated (many more details in the [Readme][readme]) -- Is a reusable working example known as a Guided Exploration ([Guided Exploration Manifesto][guided-exploration-manifesto]) - so job logs and package artifacts can be reviewed. The project can also be imported to your own GitLab group or instance as a starting point for your own work. -- IMPORTANT: It demonstrates how to override GitLab CI's default cloning behavior so that GitVersion can do a dynamic copy. Selectively clones GitVersion.yml so that these settings take effect. This best practice demonstrates the best way to do this while avoiding a double-cloning of the project (once by GitLab Runner and once by GitVersion). -- Implements GitVersion as a CI/CD Extension that can be reused across many projects using includes. -- Implements GitVersion as a single job that runs the GitVersion container and passes the version number downstream into both _pipeline_ and _job_ level variables, which means... -- It can be used with ANY coding language, framework or packaging engine. -- Generates example packaged artifacts: - - Two ways of building Sem Versioned NuGet packages (msbuild-ish and nuget.exe-ish) and uploads them and tests them from a [GitLab NuGet Repository][gitlab-nuget-repository]. - - A Sem Versioned [GitLab Generic Package][gitlab-generic-package] - - A Sem Versioned docker container and uploads to [GitLab Container Registry][gitlab-container-registry]. -- It creates a Sem Versioned [GitLab Release][gitlab-release-help] and Git tag using the [GitLab Release Cli][gitlab-release-cli] and links the generic package as evidence. +- Is a reusable working example known as a Guided Exploration ([Guided Exploration Manifesto][guided-exploration-manifesto]) - so job logs and package artifacts can be reviewed. The project can also be imported to your own GitLab group or instance as a starting point for your own work. +- IMPORTANT: It demonstrates how to override GitLab CI's default cloning behavior so that GitVersion can do a dynamic copy. Selectively clones GitVersion.yml so that these settings take effect. This best practice demonstrates the best way to do this while avoiding a double-cloning of the project (once by GitLab Runner and once by GitVersion). +- Implements GitVersion as a CI/CD Extension that can be reused across many projects using includes. +- Implements GitVersion as a single job that runs the GitVersion container and passes the version number downstream into both _pipeline_ and _job_ level variables, which means... +- It can be used with ANY coding language, framework or packaging engine. +- Generates example packaged artifacts: + - Two ways of building Sem Versioned NuGet packages (msbuild-ish and nuget.exe-ish) and uploads them and tests them from a [GitLab NuGet Repository][gitlab-nuget-repository]. + - A Sem Versioned [GitLab Generic Package][gitlab-generic-package] + - A Sem Versioned docker container and uploads to [GitLab Container Registry][gitlab-container-registry]. +- It creates a Sem Versioned [GitLab Release][gitlab-release-help] and Git tag using the [GitLab Release Cli][gitlab-release-cli] and links the generic package as evidence. [gitlab-generic-package]: https://docs.gitlab.com/ee/user/packages/generic_packages/ [gitlab-nuget-repository]: https://docs.gitlab.com/ee/user/packages/nuget_repository/ diff --git a/docs/input/docs/reference/build-servers/jenkins.md b/docs/input/docs/reference/build-servers/jenkins.md index 70f376e8f1..19669ee20f 100644 --- a/docs/input/docs/reference/build-servers/jenkins.md +++ b/docs/input/docs/reference/build-servers/jenkins.md @@ -9,13 +9,13 @@ RedirectFrom: docs/build-server-support/build-server/jenkins When setting up a Jenkins project for GitVersion, it is necessary to add a few _Behaviors_ to the SCM settings to ensure that GitVersion has enough information: -* Advanced clone behaviors - * Enable `Fetch tags` - * Enable `Honor refspec on intial clone` -* Check out to matching local branch -* Prune stale remote-tracking branches -* Specify ref specs - * Ref Spec: `+refs/heads/*:refs/remotes/@{remote}/*` +* Advanced clone behaviors + * Enable `Fetch tags` + * Enable `Honor refspec on intial clone` +* Check out to matching local branch +* Prune stale remote-tracking branches +* Specify ref specs + * Ref Spec: `+refs/heads/*:refs/remotes/@{remote}/*` ## Usage @@ -30,9 +30,9 @@ Jenkins plugins exist that provide this functionality. Of these plugins To inject the GitVersion variables as environment variables for a build job using [EnvInject][env-inject], do the following: -1. Add an **Execute Windows batch command** build step with _Command_: +1. Add an **Execute Windows batch command** build step with _Command_: `gitversion /output buildserver` -2. Add an **Inject environment variables** build step and use value +2. Add an **Inject environment variables** build step and use value 'gitversion.properties' for the _Properties File Path_ parameter This assumes GitVersion.exe is available on the command line. @@ -55,13 +55,13 @@ For pipeline projects, GitVersion variables can be accessed by reading the `gitv In a pipeline stage: -1. Run GitVersion with the flag for _buildserver_ output (this only works when run from Jenkins, specifically when the `JENKINS_URL` environment variable is defined): +1. Run GitVersion with the flag for _buildserver_ output (this only works when run from Jenkins, specifically when the `JENKINS_URL` environment variable is defined): ```groovy sh 'gitversion /output buildserver'` ``` -2. Add a script block to read the properties file, assign environment variables as needed: +2. Add a script block to read the properties file, assign environment variables as needed: ```groovy script { diff --git a/docs/input/docs/reference/build-servers/myget.md b/docs/input/docs/reference/build-servers/myget.md index fd9166aa52..c2d34846c2 100644 --- a/docs/input/docs/reference/build-servers/myget.md +++ b/docs/input/docs/reference/build-servers/myget.md @@ -8,18 +8,18 @@ RedirectFrom: docs/build-server-support/build-server/myget MyGet Build Services has built-in support for GitVersion and is encouraging you to leverage GitVersion + GitFlow to produce Semantically Versioned packages. -* Create a [custom build script](https://docs.myget.org/docs/reference/custom-build-scripts): +* Create a [custom build script](https://docs.myget.org/docs/reference/custom-build-scripts): we advise to run a tool like GitVersion in a _pre-build_ script, so that it can set additional environment variables for the actual build script. MyGet [by convention](https://docs.myget.org/docs/reference/build-services#Pre-\_and_post-build_steps) automatically picks up any of the following file names as pre-build script: - * `pre-build.(bat|cmd|ps1)` - * `pre-myget.(bat|cmd|ps1)` -* Run `GitVersion /output buildserver`: this will cause MyGet Build Services to + * `pre-build.(bat|cmd|ps1)` + * `pre-myget.(bat|cmd|ps1)` +* Run `GitVersion /output buildserver`: this will cause MyGet Build Services to set the current `%PackageVersion%` value to the NuGet-compatible SemVer generated by GitVersion and apply this [MyGet Environment Variable](https://docs.myget.org/docs/reference/build-services#Available_Environment_Variables) wherever it is used during the build process. -* Ensure the build script has been pushed to your source repository root. Done :) +* Ensure the build script has been pushed to your source repository root. Done :) :::{.alert .alert-info} **Note** diff --git a/docs/input/docs/reference/build-servers/octopus-deploy.md b/docs/input/docs/reference/build-servers/octopus-deploy.md index d802be9e62..d991fcb9fb 100644 --- a/docs/input/docs/reference/build-servers/octopus-deploy.md +++ b/docs/input/docs/reference/build-servers/octopus-deploy.md @@ -35,15 +35,15 @@ depending on which build server you have this approach may or may not work for you. For instance in TFS Build vNext you cannot chain builds to publish artifacts built in one build in another. -1. Your CI build creates the stable NuGet package +1. Your CI build creates the stable NuGet package -* Do _not_ publish this package into the Octopus nuget feed + * Do _not_ publish this package into the Octopus nuget feed -2. When you want to push a package into the Octopus deployment pipeline you trigger the second build +2. When you want to push a package into the Octopus deployment pipeline you trigger the second build -* it will either take the package built from the first build in the chain (your CI build?) or rebuild -* It will publish that package into the Octopus deploy feed -* The build then is _tagged_ with the version, this will cause GitVersion to increment the version + * it will either take the package built from the first build in the chain (your CI build?) or rebuild + * It will publish that package into the Octopus deploy feed + * The build then is _tagged_ with the version, this will cause GitVersion to increment the version This means that CI builds are _not_ available to Octopus deploy, there will be a manual build in your _build server_ which pushes the package to Octopus deploy. @@ -52,14 +52,14 @@ manual build in your _build server_ which pushes the package to Octopus deploy. Another simple option is to tag a stable version to release, the basic idea is: -1. GitVersion is set to continuous deployment mode, so main will create `-ci.x` +1. GitVersion is set to continuous deployment mode, so main will create `-ci.x` pre-release builds -2. CI Builds only create NuGet packages for stable builds -3. You tag main with a stable version of the next version then push it -4. The CI build triggers, GitVersion will always respect tags so you will get a +2. CI Builds only create NuGet packages for stable builds +3. You tag main with a stable version of the next version then push it +4. The CI build triggers, GitVersion will always respect tags so you will get a stable version -5. The stable package will be pushed to Octopus -6. Because of the tag, then next build will be incremented and will be producing +5. The stable package will be pushed to Octopus +6. Because of the tag, then next build will be incremented and will be producing pre-release packages of the next build #### Script to create the release diff --git a/docs/input/docs/reference/build-servers/teamcity.md b/docs/input/docs/reference/build-servers/teamcity.md index da4e7aad01..371bd3106e 100644 --- a/docs/input/docs/reference/build-servers/teamcity.md +++ b/docs/input/docs/reference/build-servers/teamcity.md @@ -9,10 +9,10 @@ RedirectFrom: docs/build-server-support/build-server/teamcity In [TeamCity][teamcity] you can create a build step as follows: -* **Runner type:** Command Line -* **Run:** Executable with parameters -* **Command executable:** `GitVersion.exe` -* **Command parameters:** `/output buildserver /updateassemblyinfo true` +* **Runner type:** Command Line +* **Run:** Executable with parameters +* **Command executable:** `GitVersion.exe` +* **Command parameters:** `/output buildserver /updateassemblyinfo true` Then in your build parameters simply [add a placeholder](#nuget-in-teamcity) of the GitVersion variables you would like to use. @@ -61,23 +61,23 @@ See [dynamic repositories][dynamic-repo] for more info. ### Output -* We update the TC build number to the GitVersion number automatically -* We output the individual values of the GitVersion version variables as build +* We update the TC build number to the GitVersion number automatically +* We output the individual values of the GitVersion version variables as build parameters with format `GitVersion.*` (Eg: `GitVersion.Major`) if you need access to them in your build script. Being system variables they will be passed as msbuild/environmental variables to other build steps ### NuGet in TeamCity -* Add a dummy [parameter][parameter] to the project called `GitVersion.NuGetVersion`. If +* Add a dummy [parameter][parameter] to the project called `GitVersion.NuGetVersion`. If many of your projects uses git-flow and SemVer you can add the parameter to the "root-project" (TeamCity 8.x+). You need a dummy param because GitVersion creates the variables at runtime, and you cannot reference a parameter which is not available statically. GitVersion will overwrite the dummy value. -* Then setup you nuget pack build set the "version" to +* Then setup you nuget pack build set the "version" to `%GitVersion.NuGetVersion%`. -* If you do your pack in a build script then you can just use environmental +* If you do your pack in a build script then you can just use environmental variables because teamcity will pass them through automatically. ### When TeamCity -> GitHub can't use https @@ -101,7 +101,7 @@ Sorry ## Guides -* [Continuous Delivery Setup in TeamCity][cd] +* [Continuous Delivery Setup in TeamCity][cd] [cd]: https://jake.ginnivan.net/blog/2014/07/09/my-typical-teamcity-build-setup [dynamic-repo]: /docs/learn/dynamic-repositories diff --git a/docs/input/docs/reference/configuration.md b/docs/input/docs/reference/configuration.md index 7cf48b6975..25cdeb4bc9 100644 --- a/docs/input/docs/reference/configuration.md +++ b/docs/input/docs/reference/configuration.md @@ -31,12 +31,12 @@ found that is generally what is needed when using GitFlow. To see the effective configuration (defaults and overrides), you can run `gitversion /showConfig`. - ## Global configuration The following supported workflow configurations are available in GitVersion and can be referenced by the workflow property: -- GitFlow (GitFlow/v1) -- GitHubFlow (GitHubFlow/v1) + +- GitFlow (GitFlow/v1) +- GitHubFlow (GitHubFlow/v1) Example of using a `GitHubFlow` workflow with a different `tag-prefix`: @@ -342,6 +342,7 @@ The details of the available options are as follows: ### workflow 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. + ### next-version Allows you to bump the next version explicitly. Useful for bumping `main` or a @@ -527,9 +528,9 @@ merge-message-formats: The regular expression should contain the following capture groups: -* `SourceBranch` - Identifies the source branch of the merge -* `TargetBranch` - Identifies the target branch of the merge -* `PullRequestNumber` - Captures the pull-request number +- `SourceBranch` - Identifies the source branch of the merge +- `TargetBranch` - Identifies the target branch of the merge +- `PullRequestNumber` - Captures the pull-request number Custom merge message formats are evaluated _before_ any built in formats. Support for [Conventional Commits][conventional-commits] can be @@ -635,7 +636,7 @@ values, but here they are if you need to: ### regex This is the regex which is used to match the current branch to the correct -branch configuration. +branch configuration. [Named groups](https://learn.microsoft.com/en-us/dotnet/standard/base-types/grouping-constructs-in-regular-expressions#named-matched-subexpressions) can be used to dynamically label pre-releases based on the branch name, or parts of it. See [Label](#label) for more details and examples. @@ -657,16 +658,16 @@ Take this commit graph 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 +- 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`. @@ -726,7 +727,7 @@ Same as for the [global configuration, explained above](#mode). ### label 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](#regex). +insert the value of the named group `BranchName` from the [regular expression](#regex). For example: branch `feature/foo` would become a pre-release label of `alpha.foo` with `label: 'alpha.{BranchName}'` and `regex: '^features?[/-](?.+)'`. @@ -830,29 +831,29 @@ Can be `Strict` - using the [regex](https://regex101.com/r/Ly7O1x/3/) or `Loose` the old way of parsing. The default if not specified is `Strict` Example of invalid `Strict`, but valid `Loose` -``` +``` log 1.2-alpha4 01.02.03-rc03 1.2.3.4 ``` +### strategies + +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 + [1145]: https://github.com/GitTools/GitVersion/issues/1145 [1366]: https://github.com/GitTools/GitVersion/issues/1366 [2506]: https://github.com/GitTools/GitVersion/pull/2506#issuecomment-754754037 [conventional-commits-config]: /docs/reference/version-increments#conventional-commit-messages [conventional-commits]: https://www.conventionalcommits.org/ -[installing]: /docs/usage/cli/installation [modes]: /docs/reference/modes [variables]: /docs/reference/variables [version-sources]: /docs/reference/version-sources - -### strategies - -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 diff --git a/docs/input/docs/reference/modes/continuous-delivery.md b/docs/input/docs/reference/modes/continuous-delivery.md index b8d306fb42..a1e824ca91 100644 --- a/docs/input/docs/reference/modes/continuous-delivery.md +++ b/docs/input/docs/reference/modes/continuous-delivery.md @@ -19,13 +19,13 @@ you have deployed into production. In essence continuous delivery means: -* Your code is automatically built and tested -* If any of the automated tests fail, the team's #1 priority is to fix the +* Your code is automatically built and tested +* If any of the automated tests fail, the team's #1 priority is to fix the build -* If the build is green, the application can be deployed at any time - * Ideally the business should make that decision - * The same artifacts which were built and tested should be deployed - * That means no rebuilding everything when you are deploying +* If the build is green, the application can be deployed at any time + * Ideally the business should make that decision + * The same artifacts which were built and tested should be deployed + * That means no rebuilding everything when you are deploying Continuous delivery does not work well with GitFlow. The reason is that you are required to _merge_ to main to do a release, triggering a rebuild and a new @@ -55,19 +55,19 @@ to deploy to production and it is a human choice to deploy. This means that GitVersion will build **the same semantic version** until that version is deployed. For instance: -* 1.1.0+5 -* 1.1.0+6 -* 1.1.0+7 <-- This is the artifact we release, tag the commit which created +* 1.1.0+5 +* 1.1.0+6 +* 1.1.0+7 <-- This is the artifact we release, tag the commit which created this version -* 1.1.1+0 +* 1.1.1+0 Tags are required in this mode to communicate when the release is done as it's an external manual process. ## Resources -* [Continuous Delivery on Wikipedia][wikipedia] -* [Continuous Delivery, the book][book] +* [Continuous Delivery on Wikipedia][wikipedia] +* [Continuous Delivery, the book][book] [book]: https://www.amazon.com/Continuous-Delivery-Deployment-Automation-Addison-Wesley/dp/0321601912 [configuration]: /docs/reference/configuration diff --git a/docs/input/docs/reference/modes/mainline.md b/docs/input/docs/reference/modes/mainline.md index 10b8ccf22e..d88129e418 100644 --- a/docs/input/docs/reference/modes/mainline.md +++ b/docs/input/docs/reference/modes/mainline.md @@ -34,13 +34,15 @@ and the version number which will be deployed are often different. This mode is great if you do not want to tag each release because you simply deploy every commit to main. The behaviour of this mode is as follows: -1. Calculate a base version (likely a tag in this mode) -2. Walk all commits from the base version commit -3. When a merge commit is found: - * Calculate increments for each direct commit on main - * Calculate the increment for the branch -4. Calculate increments for each remaining direct commit -5. For feature branches then calculate increment for the commits so far on your +1. Calculate a base version (likely a tag in this mode) +2. Walk all commits from the base version commit +3. When a merge commit is found: + + * Calculate increments for each direct commit on main + * Calculate the increment for the branch + +4. Calculate increments for each remaining direct commit +5. For feature branches then calculate increment for the commits so far on your feature branch. If you _do not want_ GitVersion to treat a commit or a pull request as a release diff --git a/docs/input/docs/reference/requirements.md b/docs/input/docs/reference/requirements.md index 91a2785b80..fd205ea8aa 100644 --- a/docs/input/docs/reference/requirements.md +++ b/docs/input/docs/reference/requirements.md @@ -42,7 +42,6 @@ If it is ambigous which reference (branch or tag) is being built, which is often the case on build servers, the `Git_Branch` environment variable needs to be defined and set to the reference being built. -[git-switch]: https://git-scm.com/docs/git-switch [git-unshallow]: https://git-scm.com/docs/git-fetch#Documentation/git-fetch.txt---unshallow [gitflow]: /docs/learn/branching-strategies/gitflow [build-servers]: /docs/reference/build-servers diff --git a/docs/input/docs/reference/version-increments.md b/docs/input/docs/reference/version-increments.md index dc58676a0f..27cf1d6b33 100644 --- a/docs/input/docs/reference/version-increments.md +++ b/docs/input/docs/reference/version-increments.md @@ -127,6 +127,7 @@ from the branch name as a source. However, GitVersion can't use the [branch name as a version source for _other branches_][faq-branch-name-source]. ### Detached HEAD + If HEAD is in detached state tag will be `-no-branch-`. Example: `0.0.1--no-branch-.1+4` @@ -142,7 +143,6 @@ you perform a default `git push`. Instead, tags can be pushed separately with their own command. For more information, read the [git documentation on tagging][git-tagging]. - ### Incrementing per commit When using the continuous deployment `mode` (which will increment the SemVer @@ -175,4 +175,4 @@ For more information/background on why we have come to this conclusion, read [continuous-delivery]: /docs/reference/modes/continuous-delivery [conventional-commits]: https://www.conventionalcommits.org/ [faq-branch-name-source]: /docs/learn/faq#merged-branch-names-as-version-source -[git-tagging]: https://git-scm.com/book/en/v2/Git-Basics-Tagging \ No newline at end of file +[git-tagging]: https://git-scm.com/book/en/v2/Git-Basics-Tagging diff --git a/docs/input/docs/reference/version-sources.md b/docs/input/docs/reference/version-sources.md index e58b7c4beb..c12adfd217 100644 --- a/docs/input/docs/reference/version-sources.md +++ b/docs/input/docs/reference/version-sources.md @@ -11,12 +11,12 @@ version should be. The logic of GitVersion is something like this: -* Is the current commit tagged - * Yes: Use the tag as the version - * No: continue -* Calculate the base version (highest version from all the sources) -* Increment version if needed based on branch config -* Calculate the build metadata (everything after the +) and append to the +* Is the current commit tagged + * Yes: Use the tag as the version + * No: continue +* Calculate the base version (highest version from all the sources) +* Increment version if needed based on branch config +* Calculate the build metadata (everything after the +) and append to the calculated version ## Version Sources @@ -50,9 +50,9 @@ Will increment: false For the develop branch, i.e. marked with `is-develop: true` -* Returns the version number extracted from any child release-branches, i.e. +* Returns the version number extracted from any child release-branches, i.e. those marked with `is-release-branch: true` -* Returns the version number of any tags on the main branch +* Returns the version number of any tags on the main branch Will increment: true diff --git a/docs/input/docs/usage/cli/arguments.md b/docs/input/docs/usage/cli/arguments.md index 059d1c385d..2013651a22 100644 --- a/docs/input/docs/usage/cli/arguments.md +++ b/docs/input/docs/usage/cli/arguments.md @@ -111,24 +111,24 @@ Double quote character inside of the double quoted `value` has to be be escaped 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` -7. `commit-date-format` -8. `commit-message-incrementing` -10. `label` -11. `increment` -13. `major-version-bump-message` -14. `minor-version-bump-message` -15. `mode` -16. `next-version` -17. `no-bump-message` -18. `patch-version-bump-message` -19. `tag-prefix` -20. `tag-pre-release-weight` -21. `update-build-number` +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. `label` +9. `increment` +10. `major-version-bump-message` +11. `minor-version-bump-message` +12. `mode` +13. `next-version` +14. `no-bump-message` +15. `patch-version-bump-message` +16. `tag-prefix` +17. `tag-pre-release-weight` +18. `update-build-number` Read more about [Configuration](/docs/reference/configuration). diff --git a/docs/input/docs/usage/cli/assembly-patch.md b/docs/input/docs/usage/cli/assembly-patch.md index 704044e0fd..ef1a7b2f07 100644 --- a/docs/input/docs/usage/cli/assembly-patch.md +++ b/docs/input/docs/usage/cli/assembly-patch.md @@ -10,10 +10,10 @@ Description: | `AssemblyInfo.cs` or `AssemblyInfo.vb` files in the git repo and update them. It will update the following assembly attributes: -* `AssemblyVersion` will be set to the `AssemblySemVer` variable. -* `AssemblyFileVersion` will be set to the `MajorMinorPatch` variable with an +* `AssemblyVersion` will be set to the `AssemblySemVer` variable. +* `AssemblyFileVersion` will be set to the `MajorMinorPatch` variable with an appended `.0`. -* `AssemblyInformationalVersion` will be set to the `InformationalVersion` +* `AssemblyInformationalVersion` will be set to the `InformationalVersion` variable. Note that contrary to when using the [MSBuild Task][msbuild-task] the @@ -29,10 +29,10 @@ already exist. Use the `/ensureassemblyinfo` switch alongside `/updateassemblyinfo `, if the filename specified does not exist it will be generated based on a known template that adds: -* `AssemblyVersion` will be set to the `AssemblySemVer` variable. -* `AssemblyFileVersion` will be set to the `MajorMinorPatch` variable with an +* `AssemblyVersion` will be set to the `AssemblySemVer` variable. +* `AssemblyFileVersion` will be set to the `MajorMinorPatch` variable with an appended `.0`. -* `AssemblyInformationalVersion` will be set to the `InformationalVersion` +* `AssemblyInformationalVersion` will be set to the `InformationalVersion` variable. This can be done for \*.cs, \*.vb and \*.fs files. diff --git a/docs/input/docs/usage/msbuild.md b/docs/input/docs/usage/msbuild.md index 23c158ac73..d76398b578 100644 --- a/docs/input/docs/usage/msbuild.md +++ b/docs/input/docs/usage/msbuild.md @@ -94,7 +94,7 @@ are set and how you can use them in MSBuild tasks. ## Configuration The [configuration file](/docs/reference/configuration), if any, is read from a file -the `GitVersion.yml` the root of the repository or the project directory. Since version 3, +the `GitVersion.yml` the root of the repository or the project directory. Since version 3, the path to the configuration file itself [cannot be configured](https://github.com/GitTools/GitVersion/issues/3009). ## How does it work? @@ -127,10 +127,10 @@ Default sample: Now, when you build: -* `AssemblyVersion` will be set to the `AssemblySemVer` variable. -* `AssemblyFileVersion` will be set to the `MajorMinorPatch` variable with `.0` +* `AssemblyVersion` will be set to the `AssemblySemVer` variable. +* `AssemblyFileVersion` will be set to the `MajorMinorPatch` variable with `.0` appended to it. -* `AssemblyInformationalVersion` will be set to the `InformationalVersion` variable. +* `AssemblyInformationalVersion` will be set to the `InformationalVersion` variable. #### Other injected Variables