# dotnet/nerdbank.gitversioning architecture

> Architecture diagram of the GitHub repository dotnet/nerdbank.gitversioning, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dotnet/nerdbank.gitversioning
- Repository: https://github.com/dotnet/nerdbank.gitversioning

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
graph TD
    VC["version.json"]:::config

    subgraph "Invocation Points"
        MSBUILD["MSBuild Tasks"]:::dotnet
        CLI["CLI (nbgv)"]:::dotnet
        NPM["npm / Gulp"]:::node
        CAKE["Cake Add-in"]:::dotnet
    end

    CORE["Core Library<br/>(NerdBank.GitVersioning)"]:::dotnet

    subgraph "Providers"
        MG["ManagedGit"]:::dotnet
        LG["LibGit2"]:::dotnet
        NG["NoGit"]:::dotnet
        DG["DisabledGit"]:::dotnet
        CBS["CloudBuildServices"]:::dotnet
    end

    subgraph "External Systems"
        GR["Git Repository"]:::ext
        CI["CI/CD Servers"]:::ext
    end

    DOC["Documentation Site"]:::doc
    TEST["Tests & Benchmarks"]:::test

    %% Flow: Invocation to Core
    MSBUILD -->|invokes| CORE
    CLI -->|invokes| CORE
    NPM -->|invokes| CORE
    CAKE -->|invokes| CORE
    VC -->|reads| CORE

    %% Core to Providers
    CORE -->|use| MG
    CORE -->|use| LG
    CORE -.->|fallback| NG
    CORE -.->|fallback| DG
    CORE -->|invoke| CBS

    %% Providers to External
    MG -->|git data| GR
    LG -->|git data| GR
    NG -->|no repo| GR
    DG -->|cached| GR
    CBS -->|cloud metadata| CI

    %% Outputs back to Invocation
    CORE -->|version info| MSBUILD
    CORE -->|version info| CLI
    CORE -->|version info| NPM
    CORE -->|version info| CAKE

    %% Documentation and Tests
    DOC -->|docs for| CORE
    TEST -->|validate| CORE
    TEST -->|validate| MSBUILD
    TEST -->|validate| CLI
    TEST -->|validate| CAKE

    %% Click Events
    click VC "https://github.com/dotnet/nerdbank.gitversioning/blob/main/version.json"
    click CORE "https://github.com/dotnet/nerdbank.gitversioning/blob/main/src/NerdBank.GitVersioning/Nerdbank.GitVersioning.csproj"
    click MG "https://github.com/dotnet/nerdbank.gitversioning/tree/main/src/NerdBank.GitVersioning/ManagedGit/"
    click LG "https://github.com/dotnet/nerdbank.gitversioning/tree/main/src/NerdBank.GitVersioning/LibGit2/"
    click NG "https://github.com/dotnet/nerdbank.gitversioning/tree/main/src/NerdBank.GitVersioning/NoGit/"
    click DG "https://github.com/dotnet/nerdbank.gitversioning/tree/main/src/NerdBank.GitVersioning/DisabledGit/"
    click CBS "https://github.com/dotnet/nerdbank.gitversioning/tree/main/src/NerdBank.GitVersioning/CloudBuildServices/"
    click MSBUILD "https://github.com/dotnet/nerdbank.gitversioning/blob/main/src/Nerdbank.GitVersioning.Tasks/Nerdbank.GitVersioning.Tasks.csproj"
    click MSBUILD "https://github.com/dotnet/nerdbank.gitversioning/blob/main/src/Nerdbank.GitVersioning.Tasks/Nerdbank.GitVersioning.Tasks.targets"
    click CLI "https://github.com/dotnet/nerdbank.gitversioning/blob/main/src/nbgv/nbgv.csproj"
    click CLI "https://github.com/dotnet/nerdbank.gitversioning/blob/main/src/nbgv/Program.cs"
    click NPM "https://github.com/dotnet/nerdbank.gitversioning/tree/main/src/nerdbank-gitversioning.npm/"
    click CAKE "https://github.com/dotnet/nerdbank.gitversioning/blob/main/src/Cake.GitVersioning/Cake.GitVersioning.csproj"
    click DOC "https://github.com/dotnet/nerdbank.gitversioning/tree/main/docfx/"
    click TEST "https://github.com/dotnet/nerdbank.gitversioning/tree/main/test/Nerdbank.GitVersioning.Tests/"

    %% Styles
    classDef dotnet fill:#CEF,stroke:#333,stroke-width:1px
    classDef node fill:#CFC,stroke:#333,stroke-width:1px
    classDef ext fill:#EEE,stroke:#666,stroke-width:1px,stroke-dasharray: 2 2
    classDef config fill:#FCF,stroke:#333,stroke-width:1px
    classDef doc fill:#FCC,stroke:#333,stroke-width:1px
    classDef test fill:#FDF,stroke:#333,stroke-width:1px
```
