How dotnet/nerdbank.gitversioning works
Project type and purpose
• This is an open-source .NET/NPM toolset (“Nerdbank.GitVersioning”) that computes semantic versions from Git history and integrates with MSBuild, NPM, Gulp, Cake, CLI, and CI/CD pipelines to stamp assemblies and packages.
Key components (derived from src/ and README)
a. Version configuration
• version.json – user-authored file specifying base Major.Minor, prerelease tags, placement of Git “height.”
b. Core versioning library
• Namespace: NerdBank.GitVersioning
• Reads Git data (via LibGit2, ManagedGit, NoGit, DisabledGit providers)
• Computes SemanticVersion objects, back-calculates commit corresponds.
c. MSBuild integration
• Nerdbank.GitVersioning.Tasks – MSBuild tasks/targets that call the core library during build, emit ThisAssembly class and version assets.
d. CLI tool (“nbgv”)
• src/nbgv – .NET console app exposing version-computation commands.
e. NPM package
• src/nerdbank-gitversioning.npm – Node wrapper, gulp tasks, TypeScript library exposing same core logic via JS interop.
f. Cake add-in
• src/Cake.GitVersioning – Cake aliases to call core library in Cake scripts.
g. Cloud build services adaptors
• src/NerdBank.GitVersioning/CloudBuildServices – classes for AppVeyor, GitHubActions, Travis, Jenkins, TeamCity, etc.
h. Documentation site
• docfx – DocFX configuration and markdown docs.
i. Tests & Benchmarks
• test/… – xUnit tests, benchmarks for core library, CLI, MSBuild integration, ManagedGit, LibGit2.
Relationships and data flow
1. Developer or CI pipeline invokes one of:
– MSBuild (via tasks/targets)
– nbgv CLI
– npm script / gulp
– Cake script
2. That “front-end” calls the core versioning library, passing path to version.json.
3. Core library loads Git context through one of several providers:
– ManagedGit (pure C# implementation)
– LibGit2 (native interop)
– NoGit (fallback when no repo)
– DisabledGit (dummy for build-time caching)
4. Core library computes SemanticVersion + git commit ID + cloud build metadata (using ICloudBuild instances for each CI service).
5. Outputs:
– Generated C# code (ThisAssembly) injected into compilation
– MSBuild properties & items for NuGet, VSIX, assemblies
– CLI text or JSON output
– npm package version fields
– Cloud build build‐display name update
6. External dependencies:
– Git repositories (local or remote)
– CI/CD servers (AppVeyor, GitHub Actions, etc.)
– Developer IDE (Visual Studio, VS Code)
Architectural patterns and design principles
• Plugin/Provider pattern for Git contexts and CloudBuild services
• Separation of concerns between front-end (CLI, tasks, npm, Cake) and core library
• Single source of version configuration (version.json)
• Extensibility via IoC (ICloudBuild, IGitContext)
• Cross-platform compatibility (pure managed code + native libgit2)
Essential elements
• IInvocation interface (conceptual) linking front-ends
• External systems: Git repo, CI servers