Merge remote-tracking branch 'upstream/master' into release/4.0.0

Author: JakeGinnivan

.gitignore

@@ -38,11 +38,6 @@
 ##  If you have NuGet Package Restore enabled, uncomment this
 packages/
 ForSample/
-*NugetTaskBuild*
-*NugetRefBuild*
-*NugetExeBuild*
-*GitVersionVsoTaskBuild*
-*GemBuild*
 
 # Visual Studio profiler
 *.psess
@@ -87,11 +82,8 @@ Thumbs.db
 Desktop.ini
 
 _NCrunch_GitVersion
-NuGetCommandLineBuild/
 GitVersion.sln.ide/
 .vs/
-NuGetExeBuild/
-NuGetRefBuild/
 Packages/
-NuGetTaskBuild/
+build/
 site/

build/Build.cmd renamed to Build.cmd

@@ -1,7 +1,7 @@
 @echo on
 
 set framework=v4.0.30319
-set src=%~dp0..\src\
+set src=%~dp0src\
 
 "%src%.nuget\nuget.exe" restore %src%
 
@@ -10,8 +10,8 @@ set src=%~dp0..\src\
 rmdir /s /q "%tmp%GitVersion"
 md "%tmp%GitVersion"
 
-xcopy /E "%~dp0NuGetCommandLineBuild\tools" "%tmp%GitVersion"
+xcopy /E "%~dp0build\NuGetCommandLineBuild\tools" "%tmp%GitVersion"
 
 "%tmp%GitVersion\GitVersion.exe" /l console /output buildserver /updateAssemblyInfo /proj "%src%GitVersion.sln"
 
-rmdir  /s /q "%tmp%GitVersion" 
+rmdir /s /q "%tmp%GitVersion"

CONTRIBUTING.md

@@ -4,7 +4,7 @@ We love contributions to get started contributing you might need:
  - [Get started with git](http://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](http://up-for-grabs.net/), our up for grabs issues are tagged `up-for-grabs`
- - An understanding of our [architecture](#architecture) and how [we write tests](#writing-tests)
+ - An understanding of our [http://gitversion.readthedocs.org/en/latest/more-info/how-it-works/#architecture](#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.

README.md

@@ -18,7 +18,7 @@ Versioning when using git, solved. GitVersion looks at your git history and work
  - [Documentation](http://gitversion.readthedocs.org/en/latest)
  - [Contributing](https://github.com/GitTools/GitVersion/blob/master/CONTRIBUTING.md)
  - [Why GitVersion](http://gitversion.readthedocs.org/en/latest/why)
- - [Usage](http://gitversion.readthedocs.org/en/latest/usage)
+ - [Usage](http://gitversion.readthedocs.org/en/latest/usage/usage/)
  - [How it works](http://gitversion.readthedocs.org/en/latest/more-info/how-it-works/)
  - [FAQ](http://gitversion.readthedocs.org/en/latest/faq/)
  - [Who is using GitVersion](http://gitversion.readthedocs.org/en/latest/who/)

appveyor.yml

@@ -24,9 +24,8 @@ build_script:
   - cmd: 7z a "GitVersion_%GitVersion_NuGetVersion%.zip" -r .\build\NuGetCommandLineBuild\Tools\*.*
   - cmd: appveyor PushArtifact "GitVersion_%GitVersion_NuGetVersion%.zip"
 
-  - ps: .\build\Update-GitVersionVsoTaskVersion.ps1 .\build\GitVersionVsoTaskBuild\task.json $env:GitVersion_Major $env:GitVersion_Minor $env:GitVersion_Patch
-  - cmd: 7z a "GitVersionVsoBuildTask_%GitVersion_NuGetVersion%.zip" -r .\build\GitVersionVsoTaskBuild\*.*
-  - cmd: appveyor PushArtifact "GitVersionVsoBuildTask_%GitVersion_NuGetVersion%.zip"
+  - cmd: 7z a "GitVersionTfsBuildTask_%GitVersion_NuGetVersion%.zip" -r .\build\GitVersionTfsTaskBuild\*.*
+  - cmd: appveyor PushArtifact "GitVersionTfsBuildTask_%GitVersion_NuGetVersion%.zip"
 
 test_script:
   - nunit-console "src\GitVersionTask.Tests\bin\%CONFIGURATION%\GitVersionTask.Tests.dll" "src\GitVersionExe.Tests\bin\%CONFIGURATION%\GitVersionExe.Tests.dll" "src\GitVersionCore.Tests\bin\%CONFIGURATION%\GitVersionCore.Tests.dll" /noshadow

docs/build-server-support.md

@@ -0,0 +1,17 @@
+# Build Server Support
+GitVersion has support for quite a few build servers out of the box. Currently we support:
+
+ - [AppVeyor](build-server/appveyor.md)
+ - [Bamboo](build-server/bamboo.md)
+ - [Continua CI](build-server/continua.md)
+ - [Jenkins](build-server/jenkins.md)
+ - [MyGet](build-server/myget.md)
+ - [Octopus Deploy](build-server/octopus-deploy.md)
+ - [TeamCity](build-server/teamcity.md)
+ - [Team Build (TFS)](build-server/teambuild.md)
+ - [TFS Build vNext](build-server/tfs-build-vnext.md)
+ 
+When GitVersion.exe is run with the `/output buildserver` flag instead of outputting Json it will export variables to the current build server.
+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
+
+When running in MSBuild either from the [MSBuild Task](/usage/msbuild-task) or by using the `/proj myproject.sln` parameter, GitVersion will make the MSBuild variables available in the format `$(GitVersion_SemVer)`.

docs/build-server-support/build-server-support.md

@@ -34,5 +34,5 @@ The following shows an example with the corresponding git commands:
 
 This approach works well with Semantic Versioning, as you will not be burning version numbers between releases (except if a build fails to get through UAT or something, then the burnt number means something!).
 
-### Configure GitVersion to [increment per commit](../incrementing-per-commit.md)
+### Configure GitVersion to [increment per commit](../../more-info/incrementing-per-commit.md)
 As mentioned above, this means you will burn multiple versions per release. This might not be an issue for you, but can confuse consumers of your library as the version has semantic meaning.

docs/more-info/build-server-setup/appveyor.md renamed to docs/build-server-support/build-server/appveyor.md

@@ -17,17 +17,28 @@ TeamCity has support for meta-runners which allow custom tasks. There is a GitVe
  - [Project Link](https://github.com/JetBrains/meta-runner-power-pack/tree/master/gitversion)
 
 ## Running inside TeamCity
-* Make sure to use **agent checkouts** (required, server checkouts do not copy the needed `.git` directory)
-  - If you want to use *checkout on server*, see [dynamic repositories](../dynamic-repositories.md)
-* 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
+When running in TeamCIty you have two options, run using **agent checkout** or use dynamic repositories.
+
+### Agent checkout
+For GitVersion to pick up pull requests properly you need to promote the `%teamcity.build.vcs.branch.{configurationid}%` variable to a system variable called `Git_Branch`
+
+Just go to your build configuration, Parameters, click Add, Name should be `system.Git_Branch`, value should be `%teamcity.build.vcs.branch.{vcsid}%` where vcsid is your VCS root id. You should get auto completion for this.
+
+### Dynamic repositories
+To use server side checkout, you must use the dynamic repositories feature of GitVersion. Server side checkout sends just the files to the agent and not the actual .git folder. Dynamic repositories will clone your repo into a temp folder and use it to calculate version information.
+
+See [dynamic repositories](../../more-info/dynamic-repositories.md) for more info.
+
+### Output
 * We update the TC build number to the GitVersion number automatically
-* We output the individual values of the GitVersion version as the build parameter: `GitVersion.*` (Eg: `GitVersion.Major`) if you need access to them in your build script
+* 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 dummy [parameter](http://confluence.jetbrains.com/display/TCD8/Configuring+Build+Parameters) 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+)
+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 paramter which is not available statically. GitVersion will overwrite the dummy value
 * 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 variables because teamcity will pass them through automatically.
 
 ### When TeamCity -> GitHub can't use https
 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.
@@ -37,29 +48,5 @@ If however your TeamCity uses SSH to clone git repos and https is unavailable th
 > [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).
 This transport isn't implemented. Sorry
 
-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):
-
-```Powershell
-$branchBeingBuilt = . git symbolic-ref --short -q HEAD  
-. git pull 2>&1 | write-host
-foreach ($remoteBranch in . git branch -r) {
-  . git checkout $remoteBranch.Trim().Replace("origin/", "") 2>&1 | write-host
-  . git pull 2>&1 | write-host  
-}  
-. git checkout $branchBeingBuilt 2>&1 | write-host  
-exit 0
-```
-
-you should get build output like
-
-```
-[Step 1/1]: Ensure all branches are available for GitVersion (Powershell) (5s)
-[Step 1/1] From file:///C:/BuildAgent2/system/git/git-12345678
-[Step 1/1]  * [new branch]      master     -> origin/master
-[Step 1/1] Switched to a new branch 'master'
-[Step 1/1] Branch master set up to track remote branch master from origin.
-[Step 1/1] Switched to branch 'develop'
-```
-
 ## Guides
  - [Continuous Delivery Setup in TeamCity](http://jake.ginnivan.net/blog/2014/07/09/my-typical-teamcity-build-setup)

docs/more-info/build-server-setup/bamboo.md renamed to docs/build-server-support/build-server/bamboo.md

@@ -0,0 +1,59 @@
+# Team Foundation Build (vNext) Setup
+## Basic Usage
+In Team Foundation Build (the web based build system) you can call GitVersion either using the Command Line build step or install a custom build step. The custom build step requires a one-time setup to import the GitVersion task into your TFS or VSO instance.
+
+## Executing GitVersion
+### Using GitVersion with the MSBuild Task NuGet Package
+1. Add the [GitVersionTask](https://www.nuget.org/packages/GitVersionTask/) NuGet package to your projects.
+
+See [MSBuild Task](/usage/msbuild-task) for further instructions how to use the MS Build Task.
+
+### Using GitVersion with the Command Line build step
+1. Make sure to have GitVersion.exe under version control. There exists also a [Chocolatey package](https://chocolatey.org/packages/GitVersion.Portable) for installing GitVersion.exe on build agents.
+2. Add a Command Line build step to your build definition. You'll probably want to drag the task to be at or near the top to ensure it executes before your other build steps.
+3. Set the Tool parameter to `<pathToGitVersion>\GitVersion.exe`.
+4. Set the Arguments parameter to `/output buildserver /nofetch`.
+5. If you want the GitVersionTask to update AssemblyInfo files add `updateAssemblyInfo true` to the Arguments parameter. 
+6. If you want to update the build number you need to send a [logging command](https://github.com/Microsoft/vso-agent-tasks/blob/master/docs/authoring/commands.md) to TFS.
+
+### Using the custom GitVersion build step
+#### Installing/updating the custom build step
+1. Install the `tfx` command line tool as shown [here](https://github.com/Microsoft/tfs-cli/blob/master/README.md#install).
+2. For TFS 2015 On-Prem configure Basic Authentication in TFS as shown [here](https://github.com/Microsoft/tfs-cli/blob/master/docs/configureBasicAuth.md).
+3. Download the GitVersion TFS build task from the latest release on the [GitVersion releases page](https://github.com/GitTools/GitVersion/releases) and unzip.
+4. Run `tfx login` as shown [here](https://github.com/Microsoft/tfs-cli/blob/master/README.md#login).
+5. From the directory outside of where you unzipped the task, run `tfx build tasks upload .\GitVersionTfsTask --overwrite` where GitVersionTfsTask is the directory containing the files.
+6. It should successfully install.
+
+#### Using the GitVersion custom build step
+From a TFS build definition, select "Add a Step" and then in the Build category, choose GitVersion and click Add. You'll probably want to drag the task to be at or near the top to ensure it executes before your other build steps.
+
+If you want the GitVersionTask to update AssemblyInfo files, check the box in the task configuration. For advanced usage, you can pass additional options to the GitVersion exe in the Additional arguments section.
+
+The VSO build step can update your build number with GitVersion variables. See below for details.
+
+
+## Running inside TFS
+### Using the GitVersion Variables
+GitVersion passes variables in the form of `GitVersion.*` (Eg: `GitVersion.Major`) to TFS Build and also writes `GITVERSION_*` (Eg: `GITVERSION_MAJOR`) environment variables that are available for any subsequent build step. 
+See [Variables](/more-info/variables/) for an overview of available variables.
+
+
+#### Using GitVersion variables in build name
+To use GitVersion's variables in the build name, just add them in the form `$(GITVERSION_FullSemVer)` into the Build definition's build number string. Then just ensure GitVersion is called with
+`/output buildserver` and it will replace those variables with the calculated version.
+The TFS GitVersion Build Step (above) handles this too, so if you're already using that, there's nothing extra to configure.
+
+If you currently use `$(rev:.r)` in your build number, that won't work correctly if you 
+use GitVersion variables as well due to the delayed expansion of the GitVersion vars. Instead,
+You might be able to use `$(GitVersion_BuildMetaData)` to achieve a similar result.
+See [Variables](/more-info/variables/) for more info on the variables.
+
+
+#### Known limitations
+* Due to [current limitations in TFS2015 On-Prem](https://github.com/Microsoft/vso-agent-tasks/issues/380) it's currently not possible to automatically set the build version in TFS2015 On-Prem. Instead a warning similar to `##[warning]Unable to process logging event:##vso[build.updatebuildnumber 1.0.0-unstable.1` is logged.
+* Due to a known limitation in TFS 2015 On-Prem it's currently not possible to use variables added during build in inputs of subsequent build tasks, since the variables are processed at the beginning of the build. 
+As a workaround environment variables can be used in custom scripts.
+
+## Create a NuGet package in TFS
+If you use a Command Line task to build your NuPkg, use `%GITVERSION_NUGETVERSION%` as the version parameter: `nuget.exe pack path\to\my.nuspec -version %GITVERSION_NUGETVERSION%`