dotnet / nerdbank.gitversioning

Stamp your assemblies, packages and more with a unique version generated from a single, simple version.json file and include git commit IDs for non-official builds.

Nerdbank.GitVersioning

Overview

This package adds precise, semver-compatible git commit information to every assembly, VSIX, NuGet and NPM package, and more. It implicitly supports all cloud build services and CI server software because it simply uses git itself and integrates naturally in MSBuild, gulp and other build scripts.

What sets this package apart from other git-based versioning projects is:

1. Prioritize absolute build reproducibility. Every single commit can be built and produce a unique version.
2. No dependency on tags. Tags can be added to existing commits at any time. Clones may not fetch tags. No dependency on tags means better build reproducibility.
3. No dependency on branch names. Branches come and go, and a commit may belong to any number of branches. Regardless of the branch HEAD may be attached to, the build should be identical.
4. The computed version information is based on an author-defined major.minor version and an optional unstable tag, plus a shortened git commit ID.
5. This project is supported by the .NET Foundation.

Installation and Configuration

You can install Nerdbank.GitVersioning into your projects via NuGet or NPM.

• Use the nbgv .NET Core CLI tool (recommended)
• NuGet installation instructions
• NPM installation instructions
• Cake Build installation instructions

You must also create a version.json file in your repo. See migration notes if your repo already has a version.txt or version.json file from using another system.

How to leverage version stamping and runtime information

See relevant documentation for any of these topics:

• .NET
• Node
• VSIX
• NuProj

Build

We have docs to describe how to build with Nerdbank.GitVersioning for these build systems:

• MSBuild
• gulp
• DNX
• dotnet CLI
• Cake Build

Also some special cloud build considerations (e.g. Azure Pipelines, GitHub Actions, etc.).

Where and how versions are calculated and applied

This package calculates the version based on a combination of the version.json file, the git 'height' of the version, and the git commit ID. The height can optionally be incremented only for those commits that change certain paths.

Version generation

Given the same settings as used in the discussion above, a NuGet or NPM package may be assigned this version:

1.0.24-alpha-g9a7eb6c819

When built as a public release, the git commit ID is dropped:

1.0.24-alpha

Learn more about public releases versus prereleases.

Frequently asked questions

What is 'git height'?

Git 'height' is the number of commits in the longest path from HEAD (the code you're building) to some origin point, inclusive. In this case the origin is the commit that set the major.minor version number to the values found in HEAD.

For example, if the version specified at HEAD is 3.4 and the longest path in git history from HEAD to where the version file was changed to 3.4 includes 15 commits, then the git height is "15". Another example is when HEAD points directly at the commit that changed the major.minor version, which has a git height of 1. Learn more about 1 being the minimum revision number.

Why is the git height used for the PATCH version component for public releases?

The git commit ID does not represent an alphanumerically sortable identifier in semver, and thus delivers a poor package update experience for NuGet package consumers. Incrementing the PATCH with each public release ensures that users who want to update to your latest NuGet package will reliably get the latest version.

The git height is guaranteed to always increase with each release within a given major.minor version, assuming that each release builds on a previous release. And the height automatically resets when the major or minor version numbers are incremented, which is also typically what you want.

Why isn't the git commit ID included for public releases?

It could be, but the git height serves as a pseudo-identifier already and the git commit id would just make it harder for users to type in the version number if they ever had to.

Note that the git commit ID is always included in the AssemblyInformationalVersionAttribute so one can always match a binary to the exact version of source code that produced it.

Learn more about public releases and the git commit ID suffix.

How do I translate from a version to a git commit and vice versa?

While Nerdbank.GitVersioning calculates the version and applies it to most builds automatically, there can be occasions where you want to do so yourself or reverse the process to determine the commit that produced a given version.

To do this use the nbgv tool with the get-version or get-commits command.

Another (deprecated) option is to use a pair of Powershell scripts are included in the Nerdbank.GitVersioning NuGet package that can help you to translate between the two representations.

tools\Get-CommitId.ps1
tools\Get-Version.ps1

Get-CommitId.ps1 takes a version and print out the matching commit (or possible commits, in the exceptionally rare event of a collision). Get-Version.ps1 prints out the version information for the git commit current at HEAD.

How do I build Nerdbank.GitVersioning from source?

Prerequisites and build instructions are found in our contributing guidelines.

How do I consume the latest changes prior to their release on nuget.org?

We have a public feed where our CI pushes packages. Adding the feed source URL to your nuget.config file will allow you to consume package versions that haven't been publicly released to nuget.org yet.

Code of Conduct

This project has adopted the code of conduct defined by the Contributor Covenant to clarify expected behavior in our community. For more information see the .NET Foundation Code of Conduct.

nerdbank.gitversioning's Issues

Question: Integration with Nuproj

I am working through the integration with NuProj and am trying to get it working. I had a question regarding step 2 and 3. Are these changes needed in the nuproj file, the csproj files, nuproj.targets file?

PSA: Appveyor shallow clone setting causes error - "LibGit2Sharp.NotFoundException: Object not found - failed to find pack entry"

This is more of a PSA (Public Service Announcement) + workaround rather than a bug report.

With Appveyor you can configure builds to use "shallow clone" setting clone_depth: 1 to avoid transferring the whole repo history to the build machine.
http://www.appveyor.com/docs/how-to/repository-shallow-clone

However, Nerdbank.GitVersioning needs minimum of clone_depth=2 [or leave empty to have Appveyor clone the entire history] otherwise build fails with error from LibGit2Sharp:

error MSB4018: LibGit2Sharp.NotFoundException: Object not found - failed to find pack entry (.....) 

I have confirmed that changing clone_depth=1 to clone_depth=2 is sufficient to avoid this issue.

[00:00:08] C:\projects\serverhost\packages\Nerdbank.GitVersioning.1.4.30\build\Nerdbank.GitVersioning.targets(38,5): error MSB4018: The "GetBuildVersion" task failed unexpectedly. [C:\projects\serverhost\ServerHost\ServerHost.csproj]
[00:00:08] C:\projects\serverhost\packages\Nerdbank.GitVersioning.1.4.30\build\Nerdbank.GitVersioning.targets(38,5): error MSB4018: LibGit2Sharp.NotFoundException: Object not found - failed to find pack entry (3f82961c75efd7cf324fdfe3703239512f0fb773) [C:\projects\serverhost\ServerHost\ServerHost.csproj]
[00:00:08] C:\projects\serverhost\packages\Nerdbank.GitVersioning.1.4.30\build\Nerdbank.GitVersioning.targets(38,5): error MSB4018:    at LibGit2Sharp.Core.Ensure.HandleError(Int32 result) [C:\projects\serverhost\ServerHost\ServerHost.csproj]
[00:00:08] C:\projects\serverhost\packages\Nerdbank.GitVersioning.1.4.30\build\Nerdbank.GitVersioning.targets(38,5): error MSB4018:    at LibGit2Sharp.Core.Proxy.git_revwalk_next(RevWalkerSafeHandle walker) [C:\projects\serverhost\ServerHost\ServerHost.csproj]
[00:00:08] C:\projects\serverhost\packages\Nerdbank.GitVersioning.1.4.30\build\Nerdbank.GitVersioning.targets(38,5): error MSB4018:    at LibGit2Sharp.CommitLog.CommitEnumerator.MoveNext() [C:\projects\serverhost\ServerHost\ServerHost.csproj]
[00:00:08] C:\projects\serverhost\packages\Nerdbank.GitVersioning.1.4.30\build\Nerdbank.GitVersioning.targets(38,5): error MSB4018:    at System.Linq.Enumerable.FirstOrDefault[TSource](IEnumerable`1 source) [C:\projects\serverhost\ServerHost\ServerHost.csproj]
[00:00:08] C:\projects\serverhost\packages\Nerdbank.GitVersioning.1.4.30\build\Nerdbank.GitVersioning.targets(38,5): error MSB4018:    at Nerdbank.GitVersioning.Tasks.GetBuildVersion.Execute() [C:\projects\serverhost\ServerHost\ServerHost.csproj]
[00:00:08] C:\projects\serverhost\packages\Nerdbank.GitVersioning.1.4.30\build\Nerdbank.GitVersioning.targets(38,5): error MSB4018:    at Microsoft.Build.BackEnd.TaskExecutionHost.Microsoft.Build.BackEnd.ITaskExecutionHost.Execute() [C:\projects\serverhost\ServerHost\ServerHost.csproj]
[00:00:08] C:\projects\serverhost\packages\Nerdbank.GitVersioning.1.4.30\build\Nerdbank.GitVersioning.targets(38,5): error MSB4018:    at Microsoft.Build.BackEnd.TaskBuilder.<ExecuteInstantiatedTask>d__26.MoveNext() [C:\projects\serverhost\ServerHost\ServerHost.csproj]

NPM package fails in package restore due to missing package on nuget

The NPM package versions with a git commit ID due to #70. This makes it search for a nuget.org package with a git commit id during package restore, which fails because it doesn't include it.

Support keeping AssemblyVersion the same while incrementing AssemblyFileVersion and NuGet package version

For backward compat, it is sometimes important to keep AssemblyVersion constant while still incrementing other versions. The version.txt file should support such a requirement.

Add version.json option for AssemblyVersion to precisely match full BuildVersion

Some projects, such as https://github.com/dotnet/corefx, set their AssemblyVersion to exactly match the NuGet package version.
I'm not sure why they have this policy, but we should enable it, even if it's not the default.

Another scenario is this project's own MSBuild Task. It is an implementation detail but must version closely with the .targets files. We've had many reports of the Task failing because the wrong version was already loaded due to MSBuild.exe processes lingering and being reused for another project that uses a different version of the .targets and Task.

❓ Should we merely use the 3rd integer (build number / git height) in the assembly version, or should we also use the 4th integer (truncated git commit ID) in the assembly version?

🅰️ We'll give the user the choice.

Support for one-line version format in 'version.txt' file, for example "14.2-prerelease".

Add AssemblyName to ThisAssembly class

Build Server support: set build server's build number to git version height during build

Might be useful to have a way to set the build number the build server uses to match the calculated version.

I realize that all build servers have different ways to do this but it is possible:

• TeamCity
• AppVeyor
• VSTS Agents

To name a few popular ones

Automatic integration with NuProj

Appveyor build should not fail due to rebuild of same commit

With cloud build numbering turned on, a repeat build in appveyor of the same commit (say, due to a tag being added, or the "Rebuild Commit" command) will fail the build when NB.GV tries to set the build number to one that collides with another that AppVeyor already has a record for.

In these instances, we should either emit a warning and continue, or perhaps add a unique suffix to the build number to resolve the collision.

GetBuildVersion fails when git history used version.json for another object

I keep getting following when trying to use the gitversioning package

1>Target "GetBuildVersion" in file "E:\Projects\Github\ravensorb\Xamarin-Forms-Labs\packages\Nerdbank.GitVersioning.1.2.1\build\Nerdbank.GitVersioning.targets" from project "E:\Projects\Github\ravensorb\Xamarin-Forms-Labs\src\XLabs.Core\XLabs.Core.csproj" (target "GenerateAssemblyInfo" depends on it):
1>Using "GetBuildVersion" task from assembly "E:\Projects\Github\ravensorb\Xamarin-Forms-Labs\packages\Nerdbank.GitVersioning.1.2.1\build\Nerdbank.GitVersioning.Tasks.dll".
1>Task "GetBuildVersion"
1>E:\Projects\Github\ravensorb\Xamarin-Forms-Labs\packages\Nerdbank.GitVersioning.1.2.1\build\Nerdbank.GitVersioning.targets(30,5): error MSB4018: The "GetBuildVersion" task failed unexpectedly.
1>E:\Projects\Github\ravensorb\Xamarin-Forms-Labs\packages\Nerdbank.GitVersioning.1.2.1\build\Nerdbank.GitVersioning.targets(30,5): error MSB4018: System.NullReferenceException: Object reference not set to an instance of an object.
1>E:\Projects\Github\ravensorb\Xamarin-Forms-Labs\packages\Nerdbank.GitVersioning.1.2.1\build\Nerdbank.GitVersioning.targets(30,5): error MSB4018:    at Nerdbank.GitVersioning.GitExtensions.GetVersionHeight(Repository repo, String repoRelativeProjectDirectory)
1>E:\Projects\Github\ravensorb\Xamarin-Forms-Labs\packages\Nerdbank.GitVersioning.1.2.1\build\Nerdbank.GitVersioning.targets(30,5): error MSB4018:    at Nerdbank.GitVersioning.Tasks.GetBuildVersion.Execute()
1>E:\Projects\Github\ravensorb\Xamarin-Forms-Labs\packages\Nerdbank.GitVersioning.1.2.1\build\Nerdbank.GitVersioning.targets(30,5): error MSB4018:    at Microsoft.Build.BackEnd.TaskExecutionHost.Microsoft.Build.BackEnd.ITaskExecutionHost.Execute()
1>E:\Projects\Github\ravensorb\Xamarin-Forms-Labs\packages\Nerdbank.GitVersioning.1.2.1\build\Nerdbank.GitVersioning.targets(30,5): error MSB4018:    at Microsoft.Build.BackEnd.TaskBuilder.<ExecuteInstantiatedTask>d__26.MoveNext()
1>Done executing task "GetBuildVersion" -- FAILED.
1>Done building target "GetBuildVersion" in project "XLabs.Core.csproj" -- FAILED.

I have tried a rebuild all, a clean and then build, a full reboot, and still I get the same errors.

Here is the contents of my version.json file (it is at the solution level). I have also tried at the project level and get the same result

{ "version": "2.0.5818" }

MSBuild AssemblyVersion property should always have 4 integer components

GitVersioning may interfere with Markup Compilation for WPF applications and cause assembly load exception at runtime

This may not be a common scenario, and it has a simple workaround, so may not need a fix. I am logging it here in case other people encounter it.

Symptom: System.IO.FileLoadException thrown when wpf is trying to load resources in InitializeComponent

Background:

• GitVersioning sets the AssemblyVersion property to something like "14.1"
• MarkupCompilePass1 WPF target picks up the AssemblyVersion property and inserts it into the generated .g.cs based on the XAML:

        public void InitializeComponent() {
            // ...
            System.Uri resourceLocater = new System.Uri("/foo;V14.1;component/bar.xaml", System.UriKind.Relative);
            // ...
        }

• At runtime, when this method gets called, it first tries to match the assembly against loaded assemblies; however that fails in this case as it tries to match against the full version (14.1.0.0)
• Because it couldn't find the assembly (even it if was already in memory), it tries to load it. Most of the times that will succeed, but in some cases (e.g. the assembly is located somewhere else, not under the probing path) you will encounter this problem

Workaround: Insert the following snippet in the affected projects

  <Target Name="ClearAssemblyVersionBeforeMarkupCompilePass1" BeforeTargets="MarkupCompilePass1">
    <PropertyGroup>
      <AssemblyVersion />
    </PropertyGroup>
  </Target>

This will clear up the AssemblyVersion right before the MarkupCompilePass1 target gets executed. This will cause the version not to be specified in the generated file, and it will successfully match the assembly against the version already loaded in memory

Add an npm package that can be used as a dev dependency to apply automatic versioning

Building without any version file throws NullReferenceException from the GetBuildVersion task

Building with tools version "4.0".
Target GetBuildVersion:
Using "GetBuildVersion" task from assembly "C:\git\Nerdbank.GitVersioning\bin\Debug\Nerdbank.GitVersioning.Tasks.dll".
Task "GetBuildVersion"
C:\Users\andarno\AppData\Local\Temp\bck15d0j.z2a\NerdBank.GitVersioning.targets(22,5): error MSB4018: The "GetBuildVersion" task failed unexpectedly.
C:\Users\andarno\AppData\Local\Temp\bck15d0j.z2a\NerdBank.GitVersioning.targets(22,5): error MSB4018: System.NullReferenceException: Object reference not set to an instance of an object.
C:\Users\andarno\AppData\Local\Temp\bck15d0j.z2a\NerdBank.GitVersioning.targets(22,5): error MSB4018: at Nerdbank.GitVersioning.Tasks.GetBuildVersion.Execute() in C:\git\Nerdbank.GitVersioning\src\NerdBank.GitVersioning.Tasks\GetBuildVersion.cs:line 103
C:\Users\andarno\AppData\Local\Temp\bck15d0j.z2a\NerdBank.GitVersioning.targets(22,5): error MSB4018: at Microsoft.Build.BackEnd.TaskExecutionHost.Microsoft.Build.BackEnd.ITaskExecutionHost.Execute()
C:\Users\andarno\AppData\Local\Temp\bck15d0j.z2a\NerdBank.GitVersioning.targets(22,5): error MSB4018: at Microsoft.Build.BackEnd.TaskBuilder.d__1.MoveNext()
Done executing task "GetBuildVersion" -- FAILED.
Done building target "GetBuildVersion" in project "test.proj" -- FAILED.

Tasks/Targets version mismatch causes build breaks

We get the following build error intermittently when running a local build and consistently when using VSO's CI support:

##[error]packages\Nerdbank.GitVersioning.1.4.19\build\Nerdbank.GitVersioning.targets(40,7): Error MSB4064: The "BuildMetadata" parameter is not supported by the "GetBuildVersion" task. Verify the parameter exists on the task, and it is a settable public instance property.

When building locally, the error appears to correlate with cleaning the solution and/or rebuilding, as opposed to simply using incremental builds.

Thanks in advance.

Tests fail unless machine has git configured

Tests fail in appveyor unless these commands are executed before the tests run:

git config --global user.name appveyor
git config --global user.email [email protected]

We should enhance the tests to not depend on machine configuration.

Add PublicKeyToken and PublicKey to ThisAssembly class

Support OS X with Xamarin Studio

Unfortunately the native part does not work :(

/Volumes/data/git/pinvoke/src/packages/Nerdbank.GitVersioning.1.5.46/build/NerdBank.GitVersioning.targets: Error: Error executing task Nerdbank.GitVersioning.Tasks.GetBuildVersion: The type initializer for 'LibGit2Sharp.Core.NativeMethods' threw an exception. (CodeGeneration).

I'll take a look into it in the future to help. For now I'll just disable that on my machine.

Fails when using a "shortcut" PSDrive

I have a PSDrive for my source repositories (e.g. Repos:). But scripts like Get-CommitId.ps1 use the $PWD or something without regard for expanding the actual file system path, and fails like so:

PS Repos:\Engine
[dev/heaths/bug241684] > .\packages\Nerdbank.GitVersioning.1.4.41\tools\Get-CommitId.ps1 1.1.22
New-Object : Exception calling ".ctor" with "2" argument(s): "Path 'Repos:\Engine' doesn't point at a valid Git
repository or workdir."
At C:\Users\heaths\Source\Repos\Engine\packages\Nerdbank.GitVersioning.1.4.41\tools\Get-CommitId.ps1:46 char:9
+ $repo = New-Object LibGit2Sharp.Repository($GitPath)
+         ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo          : InvalidOperation: (:) [New-Object], MethodInvocationException
    + FullyQualifiedErrorId : ConstructorInvokedThrowException,Microsoft.PowerShell.Commands.NewObjectCommand

You cannot call a method on a null-valued expression.
At C:\Users\heaths\Source\Repos\Engine\packages\Nerdbank.GitVersioning.1.4.41\tools\Get-CommitId.ps1:51 char:5
+     $repo.Dispose()
+     ~~~~~~~~~~~~~~~
    + CategoryInfo          : InvalidOperation: (:) [], RuntimeException
    + FullyQualifiedErrorId : InvokeMethodOnNull

Exception calling "GetCommitsFromVersion" with "3" argument(s): "Value cannot be null. Parameter name: repo"
At C:\Users\heaths\Source\Repos\Engine\packages\Nerdbank.GitVersioning.1.4.41\tools\Get-CommitId.ps1:48 char:5
+     $commit = [NerdBank.GitVersioning.GitExtensions]::GetCommitsFromV ...
+     ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo          : NotSpecified: (:) [], MethodInvocationException
    + FullyQualifiedErrorId : ArgumentNullException

Publish git version variables to VSTS

As found here

Unexpected characters at the end of generated .Version.cs file

We use Nerdbank.GitVersioning v 1.2.8. NuGet package, and while building our net46 project in VS 2015, there are some unexpected characters at the end of the generated *.Version.cs file, and the build fails with
Error CS1022 Type or namespace definition, or end-of-file expected ....Version.cs (28).

Here is the generated file with some fields in ThisAssembly class reduced to "..." for brevity, note the extra } at the end.

//------------------------------------------------------------------------------
// <auto-generated>
//     This code was generated by a tool.
//     Runtime Version:4.0.30319.42000
//
//     Changes to this file may cause incorrect behavior and will be lost if
//     the code is regenerated.
// </auto-generated>
//------------------------------------------------------------------------------

[assembly: System.Reflection.AssemblyVersionAttribute("0.1.0.0")]
[assembly: System.Reflection.AssemblyFileVersionAttribute("0.1.150.919")]
[assembly: System.Reflection.AssemblyInformationalVersionAttribute("0.1.150-alpha+g970364a3df")]


internal sealed partial class ThisAssembly {
    internal const string AssemblyVersion = "0.1.0.0";
    internal const string AssemblyFileVersion = "0.1.150.919";
    internal const string AssemblyInformationalVersion = "0.1.150-alpha+g970364a3df";
    internal const string AssemblyName = "...";
    internal const string PublicKey = @"...";
    internal const string PublicKeyToken = "...";
    internal const string RootNamespace = "...";
    private ThisAssembly() {
    }
}

}

Honor modified version file without requiring commit first

This fixes a usability quirk that a change to version.txt or version.json must be committed before the build will use the new version in the build.

Get branch name / last component for use in metadata

We like to distinguish one-off builds by including the branch name (sometimes just the last component of a develop topic branch) in the metadata of the package. It would be great if we could get this information from the build task and use it as part of the version for both binaries and nuget/npm packages.

NPM package fails in NuGet package restore due to package sources

When the nuget.org package source is missing, or when other package sources are listed and require authentication, package restore can fail.
We should specify -Source on the nuget install command line to ensure it works reliably.

Performance of GetBuildVersion task

Is there anyway to improve the performance of the GetBuildVersion task?
In my case I've a solution with about 30 projects all in the same git repository and all of them get the same version in the end. The git repository is rather large, containing more than 20.000 commits. When doing a full rebuild each invocation of GetBuildVersion takes about one second summing up to a total of about half a minute additional build time. When doing an incremental build it's usually about 5 to 10 projects which are affected adding additional 5 to 10 seconds build time which kinda hurts.
Since all of these invocations of GetBuildVersion return the same results in the end I was wondering whether or not this can be improved.

In any case thank you for this project in combination with NuProj, something I've been looking for a long time now.

Support for C++ projects

We need to generate a .h file for the ThisAssembly class, and an .rc file for the PE header version information.

Change JDate (which is not implicitly "reproducible") to git height

Support for VB projects

C# assemblyinfo is generated into VB projects. This causes compile time errors for the VB projects, obviously.

Get-Version.ps1 should make full semver string available

Return this instead of System.Version if a switch is passed in.

Sample:

Get-Versoin.ps1 -SemVer

version.txt found in repo sub directory is not (always?) picked up

Reported by @jkeech

Fix in PR #9

Nuget error upgrading to 1.4.30 - The "=" operator is missing after a named argument.

When using Visual Studio 2013 to update to the new Nerdbank.GitVersioning.1.4.30 package, I get the following PowerShell error printed in the NuGet Package Manager output window in VS.

The error appears to be benign for me, but that might be because i am doing package upgrade and so my project already has version.json file.

HTH.

The "=" operator is missing after a named argument.
At E:\Depot\GitHub\ServerHost\packages\Nerdbank.GitVersioning.1.4.30\tools\Create-VersionFile.ps1:15 char:38
+ [CmdletBinding(SupportsShouldProcess) <<<< ]
    + CategoryInfo          : ParserError: (:) [], ParseException
    + FullyQualifiedErrorId : MissingEqualsInNamedArgument

------- Updating...Nerdbank.GitVersioning 1.4.30 -------
Installing 'Nerdbank.GitVersioning 1.4.30'.
Added file 'AppVeyor.targets' to folder 'Nerdbank.GitVersioning.1.4.30\build'.
Added file 'CodeGenerationAttributes.Net40.dll' to folder 'Nerdbank.GitVersioning.1.4.30\build'.
Added file 'Nerdbank.GitVersioning.targets' to folder 'Nerdbank.GitVersioning.1.4.30\build\dotnet'.
Added file 'LibGit2Sharp.dll' to folder 'Nerdbank.GitVersioning.1.4.30\build'.
Added file 'git2-e0902fb.dll' to folder 'Nerdbank.GitVersioning.1.4.30\build\NativeBinaries\amd64'.
Added file 'git2-e0902fb.dll' to folder 'Nerdbank.GitVersioning.1.4.30\build\NativeBinaries\x86'.
Added file 'Nerdbank.GitVersioning.dll' to folder 'Nerdbank.GitVersioning.1.4.30\build'.
Added file 'NerdBank.GitVersioning.targets' to folder 'Nerdbank.GitVersioning.1.4.30\build'.
Added file 'Nerdbank.GitVersioning.Tasks.dll' to folder 'Nerdbank.GitVersioning.1.4.30\build'.
Added file 'Newtonsoft.Json.dll' to folder 'Nerdbank.GitVersioning.1.4.30\build'.
Added file 'PInvoke.MSCorEE.dll' to folder 'Nerdbank.GitVersioning.1.4.30\build'.
Added file 'Nerdbank.GitVersioning.targets' to folder 'Nerdbank.GitVersioning.1.4.30\build\portable-net+win+wpa+wp+sl+netmf+MonoAndroid+MonoTouch+Xamarin.iOS'.
Added file 'Validation.dll' to folder 'Nerdbank.GitVersioning.1.4.30\build'.
Added file 'VisualStudioTeamServices.targets' to folder 'Nerdbank.GitVersioning.1.4.30\build'.
Added file 'readme.txt' to folder 'Nerdbank.GitVersioning.1.4.30'.
Added file 'Create-VersionFile.ps1' to folder 'Nerdbank.GitVersioning.1.4.30\tools'.
Added file 'Get-CommitId.ps1' to folder 'Nerdbank.GitVersioning.1.4.30\tools'.
Added file 'Get-Version.ps1' to folder 'Nerdbank.GitVersioning.1.4.30\tools'.
Added file 'Install.ps1' to folder 'Nerdbank.GitVersioning.1.4.30\tools'.
Added file 'version.schema.json' to folder 'Nerdbank.GitVersioning.1.4.30\tools'.
Added file 'Nerdbank.GitVersioning.1.4.30.nupkg' to folder 'Nerdbank.GitVersioning.1.4.30'.
Successfully installed 'Nerdbank.GitVersioning 1.4.30'.
Looking for updates for 'Nerdbank.GitVersioning'...
Updating 'Nerdbank.GitVersioning' from version '1.4.19' to '1.4.30' in project 'ServerHost'.
Removing 'Nerdbank.GitVersioning 1.4.19' from ServerHost.
Added file 'packages.config'.
Successfully removed 'Nerdbank.GitVersioning 1.4.19' from ServerHost.
Adding 'Nerdbank.GitVersioning 1.4.30' to ServerHost.
For adding package 'Nerdbank.GitVersioning 1.4.30' to project 'ServerHost' that targets 'net45',
>> Build files are being added from 'build\portable-net+win+wpa+wp+sl+netmf+MonoAndroid+MonoTouch+Xamarin.iOS'
Added file 'packages.config'.
Successfully added 'Nerdbank.GitVersioning 1.4.30' to ServerHost.
For adding package 'Nerdbank.GitVersioning 1.4.30' to project 'ServerHost' that targets 'net45',
>> PowerShell scripts are being executed from 'tools' (not framework-specific)
Executing script file 'E:\Depot\GitHub\ServerHost\packages\Nerdbank.GitVersioning.1.4.30\tools\Install.ps1'.
Uninstalling 'Nerdbank.GitVersioning 1.4.19'.
Successfully uninstalled 'Nerdbank.GitVersioning 1.4.19'.
==============================

VSTS cloud builds should set buildnumber variable

The VSTS cloud builds have a Build.BuildNumber variable, as defined here.

Although NB.GV can set the build number, the Build.BuildNumber variable remains unchanged. Consider changing it explicitly within the build as well.

Semver 2.0 metadata fails "nuget pack" with referenced projects

While $(NuGetPackageVersion) replaces the "+" with "-" and allows nuget pack to succeed, if you use -IncludeReferencedProjects nuget because the AssemblyInformationalVersionAttribute value is invalid.

What might be nice is to allow (opt-in, to avoid breaking compat) semver 1.0 versions. We were able to work around this by hooking in our own target, but others may run into this as well.

Language without CodeDomProvider breaks build

When a project uses this package and specifies a value for the Language property in MSBuild for which no CodeDomProvider can be found, the build fails due to the inability to generate an AssemblyInfo.cs file.

This breaks the build for NuProj with the common.targets changes, as it sets Language to 'NuGet'

We should either quietly skip assemblyinfo generation, or emit a warning, in such cases.

BuildNumber property should be set unconditionally

The BuildNumber project property is set by TFS Team Build, and thus this project's idea for BuildNumber isn't applied because it is only set by this project if the property is empty beforehand. We should remove the condition.

NuPkg versions should include commit ID in version for more scenarios

The current behavior is:

	Stable	Prerelease
PublicRelease=true	1.2.3	1.2.3-pre
PublicRelease!=true	1.2.3	1.2.3-pre-gCommit

The commit ID is not exposed frequently enough to be reliably present and useful.

The current proposal is that we leverage NuGet v3's support for +buildMetadata on the package version to enhance it to this:

	Stable	Prerelease
PublicRelease=true	1.2.3	1.2.3-pre
PublicRelease!=true	1.2.3+gCommit	1.2.3-pre-gCommit

Consider being even more aggressive:

	Stable	Prerelease
PublicRelease=true	1.2.3+gCommit	1.2.3-pre+gCommit
PublicRelease!=true	1.2.3+gCommit	1.2.3-pre-gCommit

This may need to start under an optional property that folks can control. We at least need to weigh the impact on the user experience and whether these packages can be consumed by NuGet v2.x clients.

Support for MSBuild Core

Target CoreCLR with the MSBuild task and reference MSBuild Core assemblies.

Remaining work items:

• libgit2sharp needs to be a bit smarter about adding the native binaries directory to the PATH than just to use AppContext.BaseDirectory because that doesn't work for an MSBuild Task that uses it.
• figure out how to automate the build of a NuPkg with all the right files in place.
• Load the right MSBuild Tasks assembly based on whether MSBuild is running on .NET Fx or .NET Core
• Re-implement ThisAssembly code generation with Roslyn APIs
• Get tests running again (on both net45 and .NET Core)
• Get this building on appveyor
• Check that NPM package contains a nbgv.nuget folder that contains a subset of what is in the nupkg rather than a bunch of facade assemblies under build\msbuildcore

To work on Linux:

• Fix native libgit2 library loading in libgit2sharp (#112)

Support a version.json file for more options than version.txt supports

Spec

1. Support both file formats: version.txt will continue to be supported, alongside version.json. This is absolutely required so that repos already based on this project can upgrade to the latest version of this project yet continue to get the right version information for older commits.
2. Prefer version.json over version.txt when both files exist.
3. Define a json schema file so folks can get IntelliSense while modifying the file.

Consider

1. Automatically upgrade folks from version.txt to version.json when using the API to write the version file.

Build server support: build certain tags as PublicRelease=true

When branches and tags are pushed, builds are sometimes automatically scheduled on build servers. For example on AppVeyor, pushing build tags kicks off a build with the APPVEYOR_REPO_TAG_NAME environment variable preset.

We can add a releaseRefRegex field to the version.json file such that when builds are kicked off based on tags or branches that match the regular expression provided then the PublicRelease MSBuild property is set to true automatically, thus producing a build without the -gCOMMITID suffix to the NuGet package versions.

This enables the flow of a build completing and being validated, then deciding to ship that version. The developer then pushes a tag (say... "v1.0.1") and that automatically kicks off a fresh build that is just "1.0.1" instead of "1.0.1-gabc123def".

Stable versioned NuGet package with no assemblies cannot be traced back

When building a stable nuget package, such that the version is, for example, 14.1.6, tracing that version back to a commit ID using:

tools\Get-CommitId.ps1 14.1.6

Fails to produce a commit ID.

Nuget error upgrading to 1.4.30 - The "=" operator is missing after a named argument.

When using Visual Studio 2013 to update to the new Nerdbank.GitVersioning.1.4.30 package, I get the following PowerShell error printed in the NuGet Package Manager output window in VS.

The error appears to be benign for me, but that might be because i am doing package upgrade and so my project already has version.json file.

HTH.

The "=" operator is missing after a named argument.
At E:\Depot\GitHub\ServerHost\packages\Nerdbank.GitVersioning.1.4.30\tools\Create-VersionFile.ps1:15 char:38
+ [CmdletBinding(SupportsShouldProcess) <<<< ]
    + CategoryInfo          : ParserError: (:) [], ParseException
    + FullyQualifiedErrorId : MissingEqualsInNamedArgument

------- Updating...Nerdbank.GitVersioning 1.4.30 -------
Installing 'Nerdbank.GitVersioning 1.4.30'.
Added file 'AppVeyor.targets' to folder 'Nerdbank.GitVersioning.1.4.30\build'.
Added file 'CodeGenerationAttributes.Net40.dll' to folder 'Nerdbank.GitVersioning.1.4.30\build'.
Added file 'Nerdbank.GitVersioning.targets' to folder 'Nerdbank.GitVersioning.1.4.30\build\dotnet'.
Added file 'LibGit2Sharp.dll' to folder 'Nerdbank.GitVersioning.1.4.30\build'.
Added file 'git2-e0902fb.dll' to folder 'Nerdbank.GitVersioning.1.4.30\build\NativeBinaries\amd64'.
Added file 'git2-e0902fb.dll' to folder 'Nerdbank.GitVersioning.1.4.30\build\NativeBinaries\x86'.
Added file 'Nerdbank.GitVersioning.dll' to folder 'Nerdbank.GitVersioning.1.4.30\build'.
Added file 'NerdBank.GitVersioning.targets' to folder 'Nerdbank.GitVersioning.1.4.30\build'.
Added file 'Nerdbank.GitVersioning.Tasks.dll' to folder 'Nerdbank.GitVersioning.1.4.30\build'.
Added file 'Newtonsoft.Json.dll' to folder 'Nerdbank.GitVersioning.1.4.30\build'.
Added file 'PInvoke.MSCorEE.dll' to folder 'Nerdbank.GitVersioning.1.4.30\build'.
Added file 'Nerdbank.GitVersioning.targets' to folder 'Nerdbank.GitVersioning.1.4.30\build\portable-net+win+wpa+wp+sl+netmf+MonoAndroid+MonoTouch+Xamarin.iOS'.
Added file 'Validation.dll' to folder 'Nerdbank.GitVersioning.1.4.30\build'.
Added file 'VisualStudioTeamServices.targets' to folder 'Nerdbank.GitVersioning.1.4.30\build'.
Added file 'readme.txt' to folder 'Nerdbank.GitVersioning.1.4.30'.
Added file 'Create-VersionFile.ps1' to folder 'Nerdbank.GitVersioning.1.4.30\tools'.
Added file 'Get-CommitId.ps1' to folder 'Nerdbank.GitVersioning.1.4.30\tools'.
Added file 'Get-Version.ps1' to folder 'Nerdbank.GitVersioning.1.4.30\tools'.
Added file 'Install.ps1' to folder 'Nerdbank.GitVersioning.1.4.30\tools'.
Added file 'version.schema.json' to folder 'Nerdbank.GitVersioning.1.4.30\tools'.
Added file 'Nerdbank.GitVersioning.1.4.30.nupkg' to folder 'Nerdbank.GitVersioning.1.4.30'.
Successfully installed 'Nerdbank.GitVersioning 1.4.30'.
Looking for updates for 'Nerdbank.GitVersioning'...
Updating 'Nerdbank.GitVersioning' from version '1.4.19' to '1.4.30' in project 'ServerHost'.
Removing 'Nerdbank.GitVersioning 1.4.19' from ServerHost.
Added file 'packages.config'.
Successfully removed 'Nerdbank.GitVersioning 1.4.19' from ServerHost.
Adding 'Nerdbank.GitVersioning 1.4.30' to ServerHost.
For adding package 'Nerdbank.GitVersioning 1.4.30' to project 'ServerHost' that targets 'net45',
>> Build files are being added from 'build\portable-net+win+wpa+wp+sl+netmf+MonoAndroid+MonoTouch+Xamarin.iOS'
Added file 'packages.config'.
Successfully added 'Nerdbank.GitVersioning 1.4.30' to ServerHost.
For adding package 'Nerdbank.GitVersioning 1.4.30' to project 'ServerHost' that targets 'net45',
>> PowerShell scripts are being executed from 'tools' (not framework-specific)
Executing script file 'E:\Depot\GitHub\ServerHost\packages\Nerdbank.GitVersioning.1.4.30\tools\Install.ps1'.
Uninstalling 'Nerdbank.GitVersioning 1.4.19'.
Successfully uninstalled 'Nerdbank.GitVersioning 1.4.19'.
==============================

Get-Version.ps1 script fails with no parameters

.\Nerdbank.GitVersioning.NuGet\tools\Get-Version.ps1
Exception calling "GetIdAsVersion" with "2" argument(s): "Path should be relative to repo root.
Parameter name: repoRelativeProjectDirectory"

Define 'git height' in README.md

Incremental build can produce corrupted assemblyinfo file

Repro steps

1. Build, with a version.json set to "1.0-beta"
2. Change version.json to "1.0-rc"
3. Build

You'll see a build error due to the generated assemblyinfo.cs file having an extra closing curly because the shorter file isn't properly truncated.

We used to have code that was (supposed to) fix this, but I can't even find that any more where I would have expected it to be.

version.json should not be created in project directory when parent directory already has one

The test in Create-VersionFile.ps1 for whether to create the version.json only checks the immediate project directory and not parent directories.

It should be modified to walk up the directories till the root, looking for the file. This is what the NB.GV build authoring itself does so the ps1 should behave the same way.

Automate the generation of version.txt and removal of assembly attributes when the package is installed

Remove the need to manually create a version.txt file and update AssemblyInfo.cs after the NuGet package is installed. By leveraging NuGet's Install.ps1 script, we should be able to automate this process by seeding the version.txt file with the Major.Minor from the AssemblyVersion attribute in AssemblyInfo.cs.

Root dir version.json's assemblyVersion field should not influence subdirs with their own file

Allow specifying an Offset value in the version.json

In some cases it may be needed to adjust the git height value.
That could be easily be implemented by having an optional Offset value in the version.txt file.
By default, the value should be 0.

Get-Version.ps1 does not provide a field that varies with publicReleaseRefSpec

When using the Get-Version.ps1 script, the object returned does not have a field that varies based on whether the checked out branch is one of those specified by publicReleaseRefSpec in the version.json file.

This prevents npm packages from being versioned according to the same policies as a nuget package.

Builds can fail when sharing msbuild.exe processes across builds of projects with varying version of this project