You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
The easy way to use semantic versioning (semver.org) with a Git.
4
-
5
-
GitVersion uses your *git* repository branching conventions to determine the current [Semantic Version](http://semver.org) of your application. It supports [GitFlow](https://github.com/Particular/GitVersion/wiki/GitFlow) and the much simpler [GitHubFlow](https://github.com/Particular/GitVersion/wiki/GitHubFlow) and might work with others (let us know).
3
+
The easy way to use semantic versioning (semver.org) with a Git. Running GitVersion will calculate the SemVer of your application by looking at your git history.
6
4
7
5
GitVersion in action!
8
6
@@ -13,23 +11,153 @@ You are seeing:
13
11
- Pull requests being built as pre-release builds
14
12
- A branch called `release-1.0.0` producing beta v1 packages
15
13
16
-
Once a release is done, and you **tag** the commit which was released, the version will automatically be bumped. See our wiki for the rules and examples of how we increment the SemVer.
- d53ab6 - 2.0.0-rc.2+1 (Pre-release number was bumped because of the tag on previous commit)
28
+
- b5d142 - 2.0.0+0 (2.0.0 branch was merged, so master is now at 2.0.0)
29
+
30
+
This is just a small sample of the way GitVersion works. The idea is you just plug it in and you will get sensible version numbers by default. We support the following branch types ootb:
31
+
32
+
- master
33
+
- develop
34
+
- hotfix/
35
+
- feature/
36
+
- pull requests (stash, github and a few others)
37
+
- support/
38
+
- release/
39
+
40
+
If you have other branch types GitVersion is entirely configuration driven, so check out the [Configuration](#Configuration) section of the readme to understand how to make GitVersion work for you.
41
+
42
+
<aname='continuousdeployment' />
43
+
## Octopus Deploy/CI Build NuGet Packages
44
+
Those of you who have tried to do SemVer with Octopus Deploy or consume CI packages out of TeamCity would have hit
45
+
the problem that the SemVer version does not change each commit.
46
+
47
+
By default GitVersion is setup for *continuous delivery*, meaning that when you want to release you publish the artifact attached to your CI Build ([read more about what this means](https://github.com/ParticularLabs/GitVersion/wiki/Continuous-Delivery-Mode).
48
+
49
+
If you want to consume packages from you CI server, for instance Octopus Deploy is looking at TeamCity's NuGet feed then you want GitVersion's *continuous deployment mode*. See the [Configuration]
50
+
51
+
When using the continuous deployment mode all builds *must* have a pre-release tag, except for builds which are explicitly tagged as stable.
52
+
Then the build metadata (which is the commit count) is promoted to the pre-release tag. Applying those rules the above commit graph would produce:
- d53ab6 - 2.0.0-rc.2 (If there was another commit on the release branch it would be 2.0.0-rc.3)
61
+
- b5d142 - 2.0.0-ci.0 (2.0.0 branch was merged, so master is now at 2.0.0)
62
+
63
+
As you can see the versions now no longer conflict. When you want to create a stable `2.0.0` release you simply `git tag 2.0.0` then build the tag and it will produce a stable 2.0.0 package.
64
+
65
+
### NuGet Compatibility
66
+
Again, if you have used NuGet you would notice the versions above are not compatible with NuGet. GitVersion solves this by providing *variables*.
67
+
68
+
What you have seen above is the **SemVer** variable. You can use the **NuGetVersion** variable to have the version formatted in a NuGet compatible way.
69
+
So `1.0.1-rc.1+5` would become `1.0.1-rc0001`, this takes into account characters which are not allowed and NuGets crap sorting.
70
+
71
+
**note: ** The `NuGetVersion` variable is floating, so when NuGet 3.0 comes out with proper SemVer support GitVersion will switch this variable to a proper SemVer.
72
+
If you want to fix the version, use `NuGetVersionV2` which will stay the same after NuGet 3.0 comes out
73
+
74
+
## Variables
75
+
Variables are quite useful if you need different formats of the version number. Running `GitVersion.exe` in your repo will show you what is available.
76
+
For the `release/3.0.0` branch of GitVersion it shows:
GitVersion 3.0 is mainly powered by configuration and no longer has branching strategies hard coded. This means it probably can be changed to work for your scenario.
103
+
104
+
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.
105
+
Uncomment and modify as you need.
106
+
107
+
The configuration options are:
108
+
109
+
-`?assembly-versioning-scheme`: When updating assembly info tells GitVersion how to treat the AssemblyVersion attribute. Useful to lock the major when using Strong Naming.
110
+
-`mode`: Either ContinuousDelivery or ContinuousDeployment. See [Octopus Deploy/CI Build NuGet Packages](#continuousdeployment) above for more information
111
+
-`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`
112
+
113
+
Then we have branch specific configuration, which looks something like this:
114
+
115
+
```yaml
116
+
branches:
117
+
master:
118
+
tag:
119
+
increment: Patch
120
+
preventIncrementOfMergedBranchVersion: true
121
+
(pull|pull\-requests|pr)[/-]:
122
+
tag: PullRequest
123
+
increment: Inherit
124
+
tagNumberPattern: '[/-](?<number>\d+)[-/]'
125
+
```
126
+
127
+
The options in here are:
128
+
- `tag`: The pre release tag to use for this branch
129
+
- `increment`: the part of the SemVer to increment when GitVersion detects it needs to be (i.e commit after a tag)
130
+
- `preventIncrementOfMergedBranchVersion`: When `release-2.0.0` is merged into master, we want master to build `2.0.0`.
131
+
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
132
+
- `tagNumberPattern`: Pull requests require us to pull the pre-release number out of the branch name so `refs/pulls/534/merge` builds as `PullRequest.5`.
133
+
This is a regex with a named capture group called `number`
134
+
135
+
We don't envision many people needing to change most of these configuration values, but they are there if you need to.
136
+
137
+
## Build Server support
138
+
GitVersion has support for quite a few build servers out of the box. Currently we support:
139
+
140
+
- TeamCity
141
+
- AppVeyor
142
+
- Continua Ci
143
+
- MyGet
144
+
145
+
When GitVersion.exe is run with the `/output buildserver` flag instead of outputting Json it will export variables to the current build server.
146
+
For instance if you are running in TeamCity after you run `GitVersion /output buildserver` you will have the `%system.GitVersion.SemVer%` available for you to use
147
+
148
+
When running in MSBuild either from the MSBuild Task or by using the `/proj myproject.sln` GitVersion will make the MSBuild variables available in the format `$(GitVersion_SemVer)`.
149
+
150
+
## MSBuild Task/Ruby Gem/API
151
+
GitVersion has multiple ways it can be consumed.
21
152
153
+
- [A Command Line tool](https://github.com/Particular/GitVersion/wiki/Command-Line-Tool)
<a href="http://thenounproject.com/noun/tree/#icon-No13389" target="_blank">Tree</a> designed by <a href="http://thenounproject.com/david.chapman" target="_blank">David Chapman</a> from The Noun Project
0 commit comments