Trying to make the TeamCity getting started experience a bit better

Also improving the TeamCity docs

Author: JakeGinnivan

docs/build-server-support/build-server/teamcity.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](../../more-info/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)

src/GitVersionCore/BuildServers/BuildServerBase.cs

@@ -8,7 +8,7 @@ public abstract class BuildServerBase : IBuildServer
         public abstract string GenerateSetVersionMessage(VersionVariables variables);
         public abstract string[] GenerateSetParameterMessage(string name, string value);
 
-        public virtual string GetCurrentBranch()
+        public virtual string GetCurrentBranch(bool usingDynamicRepos)
         {
             return null;
         }

src/GitVersionCore/BuildServers/IBuildServer.cs

@@ -8,7 +8,7 @@ public interface IBuildServer
         string GenerateSetVersionMessage(VersionVariables variables);
         string[] GenerateSetParameterMessage(string name, string value);
         void WriteIntegration(Action<string> writer, VersionVariables variables);
-        string GetCurrentBranch();
+        string GetCurrentBranch(bool usingDynamicRepos);
         /// <summary>
         /// If the build server should not try and fetch
         /// </summary>

src/GitVersionCore/BuildServers/Jenkins.cs

@@ -34,7 +34,7 @@ public override string[] GenerateSetParameterMessage(string name, string value)
             };
         }
 
-        public override string GetCurrentBranch()
+        public override string GetCurrentBranch(bool usingDynamicRepos)
         {
             return Environment.GetEnvironmentVariable("GIT_BRANCH");
         }

src/GitVersionCore/BuildServers/TeamCity.cs

@@ -9,6 +9,39 @@ public override bool CanApplyToCurrentContext()
             return !string.IsNullOrEmpty(Environment.GetEnvironmentVariable("TEAMCITY_VERSION"));
         }
 
+        public override string GetCurrentBranch(bool usingDynamicRepos)
+        {
+            var branchName = Environment.GetEnvironmentVariable("Git_Branch");
+
+            if (string.IsNullOrEmpty(branchName))
+            {
+                if (!usingDynamicRepos)
+                {
+                    WriteBranchEnvVariableWarning();
+                }
+
+                return base.GetCurrentBranch(usingDynamicRepos);
+            }
+
+            return branchName;
+        }
+
+        static void WriteBranchEnvVariableWarning()
+        {
+            Logger.WriteWarning(@"TeamCity doesn't make the current branch available through environmental variables.
+
+Depending on your authentication and transport setup of your git VCS root things may work. In that case, ignore this warning.
+
+In your TeamCity build configuration, add a parameter called `system.Git_Branch` with value %teamcity.build.vcs.branch.<vcsid>%
+
+See http://gitversion.readthedocs.org/en/latest/build-server-support/build-server/teamcity for more info");
+        }
+
+        public override bool PreventFetch()
+        {
+            return !string.IsNullOrEmpty(Environment.GetEnvironmentVariable("Git_Branch"));
+        }
+
         public override string[] GenerateSetParameterMessage(string name, string value)
         {
             return new[]

src/GitVersionCore/BuildServers/VsoAgent.cs

@@ -19,7 +19,7 @@ public override string[] GenerateSetParameterMessage(string name, string value)
             };
         }
 
-        public override string GetCurrentBranch()
+        public override string GetCurrentBranch(bool usingDynamicRepos)
         {
             return Environment.GetEnvironmentVariable("BUILD_SOURCEBRANCH");
         }

src/GitVersionCore/ExecuteCore.cs

@@ -63,22 +63,22 @@ public bool TryGetVersion(string directory, out VersionVariables versionVariable
             }
         }
 
-        static string ResolveCurrentBranch(IBuildServer buildServer, string targetBranch)
+        static string ResolveCurrentBranch(IBuildServer buildServer, string targetBranch, bool isDynamicRepository)
         {
             if (buildServer == null)
             {
                 return targetBranch;
             }
 
-            var currentBranch = buildServer.GetCurrentBranch() ?? targetBranch;
+            var currentBranch = buildServer.GetCurrentBranch(isDynamicRepository) ?? targetBranch;
             Logger.WriteInfo("Branch from build environment: " + currentBranch);
 
             return currentBranch;
         }
 
         VersionVariables ExecuteInternal(string targetBranch, string commitId, IRepository repo, GitPreparer gitPreparer, string projectRoot, IBuildServer buildServer)
         {
-            gitPreparer.Initialise(buildServer != null, ResolveCurrentBranch(buildServer, targetBranch));
+            gitPreparer.Initialise(buildServer != null, ResolveCurrentBranch(buildServer, targetBranch, gitPreparer.IsDynamicGitRepository));
 
             var versionFinder = new GitVersionFinder();
             var configuration = ConfigurationProvider.Provide(projectRoot, fileSystem);