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:
- Prioritize absolute build reproducibility. Every single commit can be built and produce a unique version.
- 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.
- 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.
- The computed version information is based on an author-defined major.minor version and an optional unstable tag, plus a shortened git commit ID.
- This project is supported by the .NET Foundation.
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.
See relevant documentation for any of these topics:
We have docs to describe how to build with Nerdbank.GitVersioning for these build systems:
Also some special cloud build considerations (e.g. Azure Pipelines, GitHub Actions, etc.).
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.
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.
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.
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.
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.
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.
Prerequisites and build instructions are found in our contributing guidelines.
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.
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.