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.