How do I set up Nerdbank.GitVersioning in a .NET project?

Add the NuGet package to your project, and it integrates automatically with MSBuild. Create a version.json file in the repository root to define your base version and rules, and versions will be computed during builds.

Nerdbank.GitVersioning or GitVersion: which is better for CI/CD?

Nerdbank.GitVersioning excels in reproducibility without relying on git tags or branches, making it ideal for deterministic builds. GitVersion may be better if you prefer tag-based workflows or need more community plugins.

Can I use it with Azure DevOps pipelines?

Yes, it's cross-platform and works with any CI system that supports .NET or Node.js. Use the CLI tool or MSBuild tasks to compute versions, and it can update cloud build names for easy correlation.

How does it handle prerelease versions like alpha or beta?

Define prerelease labels in the version.json file, and the tool appends them based on git commit history, ensuring unique versions for development builds while maintaining semantic versioning compliance.

Is there a way to access the version number in my C# code at runtime?

Yes, it generates a ThisAssembly class with static properties like ThisAssembly.Version and ThisAssembly.Git.CommitId, providing easy runtime access to all version details without reflection.

What happens if I move commits between branches or rebase?

Since it doesn't depend on branch names, the version is computed solely from the commit history and configuration, so rebasing or merging doesn't affect reproducibility as long as commits are preserved.

Open-Awesome

GitVersioning

MITC#v3.10.91

Automatically stamps .NET assemblies, NuGet packages, and NPM packages with unique, semantic versions derived from git commits.

Visit Website GitHub

1.6k stars184 forks0 contributors

What is GitVersioning?

Nerdbank.GitVersioning is a versioning tool for .NET and Node.js projects that automatically generates unique, semantic version numbers based on git commit history. It solves the problem of manual version management by stamping assemblies, NuGet packages, and NPM packages with reproducible versions derived from a simple configuration file, ensuring every commit has a distinct version for traceability.

Target Audience

Developers and teams working on .NET or Node.js projects who need automated, reproducible versioning for continuous integration, package publishing, or build pipelines.

Value Proposition

Developers choose Nerdbank.GitVersioning for its emphasis on build reproducibility without dependencies on git tags or branch names, its seamless integration with MSBuild and NPM, and its ability to provide runtime access to version details through generated code.

Overview

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.

Use Cases

Best For

Automating version stamps for .NET assemblies and NuGet packages
Generating semantic versions for NPM packages in Node.js projects
Ensuring reproducible builds in CI/CD pipelines
Managing version numbers without relying on git tags
Providing runtime access to version information in .NET applications
Stamping cloud build names with version numbers for correlation

Not Ideal For

Projects that rely on git tags as the primary versioning mechanism for releases
Teams using build systems or languages outside .NET and Node.js ecosystems
Simple applications with infrequent releases where manual versioning suffices

Pros & Cons

Pros

Build Reproducibility

Prioritizes absolute reproducibility by not depending on git tags or branch names, ensuring every commit produces a unique version that is consistent across clones and environments.

Seamless Build Integration

Provides MSBuild and NPM integration to automatically stamp assemblies, NuGet packages, NPM packages, and executables with computed versions, streamlining CI/CD pipelines.

Runtime Version Access

Generates a ThisAssembly class in .NET projects, giving code runtime access to version information, strong name keys, and other build details without manual updates.

Flexible Configuration

Allows control over base version numbers, git height increments, and prerelease labels via a simple version.json file, enabling customized semantic versioning schemes.

Cons

.NET Runtime Dependency

Requires the .NET runtime even for Node.js projects, adding an external dependency that can complicate setup in pure JavaScript or non-.NET environments.

Limited Language Support

Primarily designed for .NET and Node.js, with no native integration for other programming languages or build tools, restricting its use in multi-language projects.

Configuration Learning Curve

Understanding concepts like git height and semantic versioning rules in version.json may require upfront learning, especially for teams new to automated versioning.

Frequently Asked Questions

Related Projects

msbuild

The Microsoft Build Engine (MSBuild) is the build platform for .NET and Visual Studio.

Stars5,541

Forks1,440

Last commit2 days ago

dotnet-docker

Official container images for .NET

Stars4,859

Forks1,974

Last commit2 days ago

Opserver

Stack Exchange's Monitoring System

Stars4,564

Forks824

Last commit1 year ago

Cake

:cake: Cake (C# Make) is a cross platform build automation system.

Stars4,181

Forks770

Last commit8 days ago

Community-curated · Updated weekly · 100% open source

Found a gem we're missing?

Open-Awesome is built by the community, for the community. Submit a project, suggest an awesome list, or help improve the catalog on GitHub.

Submit a project Star on GitHub