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
Use convention to derive a SemVer product version from a GitFlow/GitHubFlow based repository. To detect that branching model that is in use GitVersion will look for a develop branch. If a develop branch is found GitFlow based version will be appiled
3
+
The easy way to use semantic versioning (semver.org) with a Git.
4
+
5
+
*GitHubFlowVersion* will automatically version your application to SemVer of `{vLast.Major}.{vLast.Minor}.{vLast.Patch+1}` where vLast is the last **Git Tag** in your repo and furthermore, it supports detection and versioning of **Pull Requests** if you are using GitHub or Stash.
6
+
7
+
This means your versions are based on **source control metadata** making it repeatable. *GitVersion* gives you flexibility by making variables available to your build so you can meet all your versioning requirements.
8
+
9
+
It also means that unlike many other versioning strategies **you do not have to rebuild your project to bump the version!**
10
+
11
+
## Supported Branching Models
12
+
GitVersion supports both the GitFlow branching model and GitHubFlow. To read more about each of these check out our Uncyclo:
13
+
14
+
### GitFlow
15
+
Triggered when repository has a `develop` branch
16
+
17
+
-[GitFlow: A successful Git branching model](http://nvie.com/git-model/)
18
+
-[GitVersion GitFlow support wiki](https://github.com/Particular/GitVersion/wiki/GitFlow)
The command line too makes variables available for you to use, we currently support:
60
+
61
+
- Output variables to your build server for use in your build
62
+
- Return Json object to caller with variables via StdOut ([Example](https://github.com/Particular/GitVersion/blob/master/Tests/JsonVersionBuilderTests.Json.approved.txt))
63
+
- Execute your build script (msbuild) with variables passed as properties
64
+
- Execute an executable with variables available as Environmental Variables to the process
58
65
59
66
### 4. A ruby gem
60
67
If you want a ruby gem version installed on your machine then you can use [Bundler](http://bundler.io/) or Gem(http://rubygems.org/) to install GitVersion
61
68
62
69
gem install GitVersion
63
-
64
-
The calling conventions and the output are the same as the command line version.
65
-
66
-
## The Problem
67
-
68
-
Builds are getting more complex and as we're moving towards scm structure with a lot of fine grained repositories we need to take a convention based approach for our product versioning.
69
-
70
-
This also have the added benefit of forcing us to follow our branching strategy on all repositories since the build breaks if we don't.
71
-
72
-
### Assumptions:
73
-
74
-
* Using the [GitFlow branching model](http://nvie.com/git-model/) which means that we always have a master and a develop branch or the [GitHubFlow branching model](http://scottchacon.com/2011/08/31/github-flow.html) which only has a master branch.
75
-
* Following [Semantic Versioning](http://semver.org/)
76
-
* Planned releases (bumps in major or minor) are done on release branches prefixed with release-. Eg: release-4.1 (or release-4.1.0)
77
-
* Hotfixes are prefixed with hotfix- Eg. hotfix-4.0.4
78
-
* The original GitFlow model (http://nvie.com/posts/a-successful-git-branching-model/) specifies branches with a "-" separator while the git flow extensions (https://github.com/nvie/gitflow) default to a "/" separator. Either work with GitVersion.
79
-
* Tags are used on the master branch and reflects the SemVer of each stable release eg 3.3.8 , 4.0.0, etc
80
-
* Tags can also be used to override versions while we transition repositories over to GitVersion
81
-
* Using a build server with multi-branch building enabled eg TeamCity 8
82
-
83
-
### How Branches are handled
84
-
85
-
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:
86
-
87
-
*`targetBranch` => the branch we are targeting
88
-
*`targetCommit` => the commit we are targeting on `targetbranch`
89
-
90
-
#### Master branch
91
-
92
-
Commits on master will always be a merge commit (Either from a `hotfix` or a `release` branch) or a tag. As such we can simply take the commit message or tag message.
93
-
94
-
If we try to build from a commit that is no merge and no tag then assume `0.1.0`
95
-
96
-
`mergeVersion` => the SemVer extracted from `targetCommit.Message`
`releaseVersion` => the SemVer extracted from `targetBranch.Name`
151
-
`releaseTag` => the first version tag placed on the branch. Note that at least 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`
152
-
153
-
* major: `mergeVersion.Major`
154
-
* minor: `mergeVersion.Minor`
155
-
* patch: 0
156
-
* pre-release: `{releaseTag.preRelease}.{n}` where n = 1 + the number of commits since `releaseTag`.
157
-
158
-
So on a branch named `release-1.2` with a tag `1.2.0-alpha1` and 4 commits after that tag the version would be `1.2.0-alpha1.4`
Branch naming convention: anything except `master`, `develop`, `release-{n}`, or `hotfix-{n}`. Canonical branch name contains `/pull/`.
190
-
191
-
* major: `masterMergeVersion.Major`
192
-
* minor: `masterMergeVersion.Minor + 1` (0 if the override above is used)
193
-
* patch: 0
194
-
* pre-release: `unstable.pull{n}` where n = the pull request number ('0' padded to 4 characters)
195
-
196
-
### Nightly Builds
197
-
198
-
**develop**, **feature** and **pull-request** builds are considered nightly builds and as such are not in strict adherence to SemVer.
199
-
200
-
## Release Candidates
201
-
202
-
How do we do release candidates?? Perhaps tag a release branch and then count commits forward from the tag to get RC1, RC2 etc??
203
-
204
-
## Running inside TeamCity
205
-
206
-
* Make sure to use agent checkouts
207
-
* For the moment you need to promote the `%teamcity.build.vcs.branch.{configurationid}%` build parameter to an environment variable with the same name for pull requests to be handled correctly
208
-
* We update the TC build number to the GFV number automatically
209
-
* We output the individual values of the GFV version as the build parameter: `GitVersion.*` (Eg: `GitVersion.Major`) if you need access to them in your build script
210
-
211
-
### NuGet in TeamCity
212
-
* Add dummy [parameter](http://confluence.jetbrains.com/display/TCD8/Configuring+Build+Parameters) to
213
-
the project called `GitVersion.NugetVersion`. If many of your projects uses git-flow and SemVer you
214
-
can add the parameter to the "root-project" (TeamCity 8.x+)
215
-
* Then setup you nuget pack build set the "version" to `%GitVersion.NugetVersion%`
71
+
The calling conventions and the output are the same as the command line version.
216
72
217
-
### When TeamCity -> GitHub can't use https
73
+
## Supported Variables
74
+
Because not everyone is the same, we give you a bunch of different variables which you can use in your builds to meet *your* requirements
218
75
219
-
GitVersion requires the presence of master branch in order to determine the version number. If TeamCity uses https to clone git repos then GitVersion will pull down master branch for you during the build.
76
+
Examples assume 1.2.3 has been tagged 3 commits ago, we are build branch `Foo` which is a pull request (#5)
220
77
221
-
If however your TeamCity uses SSH to clone git repos and https is unavailable then GitVersion will error with a message like
78
+
-*Major*, *Minor*, *Patch*, *Tag* and *Build MetaData* (Build metadata is number of builds since last tag) - `1`, `2`, `3`, `PullRequest5`, `3`
79
+
-*FullSemVer* - The FULL SemVer including tag and build metadata `1.2.3-PullRequest5+3`
80
+
-*SemVer* - The SemVer without build metadata `1.2.3-PullRequest5`
81
+
-*AssemblySemVer* - SemVer with a 0 as the build in the assembly version `1.2.3.0`
82
+
-*ClassicVersion* - SemVer with the build metadata as build number `1.2.3.3`
83
+
-*BranchName* - The branch name `Foo`
84
+
-*Sha* - Git sha of HEAD
222
85
223
-
> [GitVersionTask.UpdateAssemblyInfo] Error occurred: GitVersion.MissingBranchException: Could not fetch from '[email protected]:Xero/Bus.git' since LibGit2 does not support the transport. You have most likely cloned using SSH. If there is a remote branch named 'master' then fetch it manually, otherwise please create a local branch named 'master'. ---> LibGit2Sharp.LibGit2SharpException: An error was raised by libgit2. Category = Net (Error).
224
-
This transport isn't implemented. Sorry
86
+
## The Problem
225
87
226
-
You need to create a TeamCity build step before your compile step which manually creates a local master branch which tracks remote master. Like so (in powershell):
88
+
Builds are getting more complex and as we're moving towards scm structure with a lot of fine grained repositories we need to take a convention based approach for our product versioning.
227
89
228
-
```Powershell
229
-
$branchBeingBuilt = . git symbolic-ref --short -q HEAD
0 commit comments