# gittools/gitversion architecture

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

- Interactive diagram: https://gitdiagram.com/gittools/gitversion
- Repository: https://github.com/gittools/gitversion

## Overview

##### Project Type and Purpose
- This is an open-source, multi-component .NET tool (GitVersion) that computes Semantic Version numbers from Git history.
- Key outputs include:
- A cross-platform CLI application (“GitVersion.Tool”)
- A .NET API/core library (“GitVersion.Core”)
- MSBuild tasks integration (“GitVersion.MsBuild”)
- Various output modules (AssemblyInfo, Wix, JSON, etc.)
- Docker images, Homebrew/Chocolatey packages, and GitHub Actions integration

##### High-Level Architecture Overview
A. Runtime components (the library, tools, and extensions)
B. CI/CD & Packaging pipeline

##### Main Components (Runtime Domain)
a. Frontends
– CLI Application (GitVersion.App)
– MSBuild Task (GitVersion.MsBuild)
– New-CLI generator (`new-cli` folder)
b. Core Engine
– GitVersion.Core (version calculation, branch strategies, deployment modes)
– Configuration Provider (GitVersion.Configuration)
– Build Agent Resolver (GitVersion.BuildAgents)
– Git abstraction layer (GitVersion.LibGit2Sharp)
c. Output Modules (GitVersion.Output)
– AssemblyInfo generator
– Project file updater
– Wix file updater
– JSON/console serializers
d. Schema Generator (GitVersion.Schema)
e. Testing Harness (GitVersion.Testing & various *.Tests projects)

##### External Dependencies
- Git repository on local file system (via LibGit2Sharp)
- Environment variables / Build Server APIs (Azure Pipelines, GitHub Actions, Jenkins, etc.)
- Package registries: NuGet, Chocolatey, Homebrew, DockerHub
- CI services: GitHub Actions, Azure Pipelines

##### Relationships and Data Flows
- User invokes CLI or MSBuild Task →
- CLI/MSBuild passes command-line args to Argument Parser →
- Configuration Provider reads YAML/JSON files →
- Build Agent Resolver detects CI environment →
- Core Engine (GitVersion.Core) uses LibGit2Sharp to scan Git history →
- Calculation modules apply version strategies →
- Core outputs version data to Output Modules →
- Output Modules write files or print JSON/console output →
- CLI/MSBuild returns exit code
- Schema Generator produces JSON schemas for configuration.
- Test projects invoke core and modules via in-memory or virtual repos.

##### CI/CD & Packaging Pipeline Components
- Workflow triggers: GitHub Actions / Azure Pipelines
- Build orchestrator: Cake scripts (in `build/*`)
- Tasks: restore, build solution, run tests, generate docs, package CLI, Docker images
- Artifact publishing:
- NuGet (GitVersion.Tool, GitVersion.MsBuild)
- Chocolatey (GitVersion.Portable)
- Homebrew formula
- Docker Hub images
- GitHub Releases

##### Architectural Patterns & Principles
- Modular design with clear separation of concerns: CLI vs. Core vs. Output
- Dependency Injection (modules wired via IContainer)
- Abstraction layers for Git (via LibGit2Sharp) and Build Agents
- Strategy pattern for version calculation (multiple IVersionStrategy implementations)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Runtime Components
    subgraph "Runtime Components"
        %% Frontends (Blue)
        subgraph "Frontends"
            App["GitVersion.App"]:::frontend
            MsBuild["GitVersion.MsBuild"]:::frontend
            NewCLI["new-cli"]:::frontend
        end

        %% Core & Config (Green)
        subgraph "Core Engine & Providers"
            Core["GitVersion.Core"]:::core
            Config["GitVersion.Configuration"]:::core
            Agents["GitVersion.BuildAgents"]:::core
            GitLib["GitVersion.LibGit2Sharp"]:::core
        end

        %% Output Modules (Orange)
        subgraph "Output Modules"
            Output["GitVersion.Output"]:::output
            AssemblyInfo["AssemblyInfo"]:::output
            ProjectUpdater["ProjectFileUpdater"]:::output
            WixUpdater["WixUpdater"]:::output
            Serializer["Serializer"]:::output
        end

        Schema["GitVersion.Schema"]:::core
        Testing["GitVersion.Testing"]:::core
    end

    %% External Dependencies (Gray)
    subgraph "External Dependencies"
        GitRepo["Git Repository"]:::external
        EnvVars["Environment Variables / CI APIs"]:::external
        NuGet["NuGet / Chocolatey / Homebrew / DockerHub"]:::external
        CIDevices["CI Services (GitHub Actions, Azure Pipelines)"]:::external
    end

    %% CI/CD & Packaging Pipeline
    subgraph "CI/CD & Packaging Pipeline"
        CI["GitHub Actions / Azure Pipelines"]:::external
        Cake["Cake Build Scripts"]:::external
        Publish["Artifact Publishing"]:::external
    end

    %% Relationships
    App -->|invoke| CLIParser["Argument Parser"]:::core
    MsBuild -->|invoke| CLIParser
    CLIParser -->|reads| Config
    CLIParser -->|detects| Agents
    Agents -->|uses| EnvVars
    Config -->|loads| GitRepo
    Core -->|calculates version| GitLib
    Core -->|calls strategies| Core
    Core -->|outputs data| Output
    Output -->|generates| AssemblyInfo
    Output -->|updates| ProjectUpdater
    Output -->|updates| WixUpdater
    Output -->|serializes| Serializer
    Output -->|prints/returns| App
    App -->|exit code| App

    Schema -->|produces| Config

    Testing -->|tests| Core
    Testing -->|tests| Output
    Testing -->|tests| Config
    Testing -->|tests| Agents
    Testing -->|tests| App
    Testing -->|tests| MsBuild

    %% CI/CD Flow
    GitRepo -->|push triggers| CI
    CI -->|runs| Cake
    Cake -->|build/tests/docs| Testing
    Cake -->|packages| App
    Cake -->|packages| MsBuild
    Cake -->|packages| Docker
    Cake -->|packages| NuGet
    Publish -->|to| NuGet
    Publish -->|to| NuGet
    Publish -->|to| NuGet
    CI -->|publishes| Publish

    %% Click Events
    click App "https://github.com/gittools/gitversion/blob/main/src/GitVersion.App"
    click MsBuild "https://github.com/gittools/gitversion/blob/main/src/GitVersion.MsBuild"
    click NewCLI "https://github.com/gittools/gitversion/tree/main/new-cli/"
    click Core "https://github.com/gittools/gitversion/blob/main/src/GitVersion.Core"
    click Config "https://github.com/gittools/gitversion/blob/main/src/GitVersion.Configuration"
    click Agents "https://github.com/gittools/gitversion/blob/main/src/GitVersion.BuildAgents"
    click GitLib "https://github.com/gittools/gitversion/blob/main/src/GitVersion.LibGit2Sharp"
    click Output "https://github.com/gittools/gitversion/blob/main/src/GitVersion.Output"
    click AssemblyInfo "https://github.com/gittools/gitversion/tree/main/src/GitVersion.Output/AssemblyInfo"
    click ProjectUpdater "https://github.com/gittools/gitversion/blob/main/src/GitVersion.Output/AssemblyInfo/ProjectFileUpdater.cs"
    click WixUpdater "https://github.com/gittools/gitversion/tree/main/src/GitVersion.Output/WixUpdater"
    click Serializer "https://github.com/gittools/gitversion/tree/main/src/GitVersion.Output/Serializer"
    click Schema "https://github.com/gittools/gitversion/blob/main/src/GitVersion.Schema"
    click Testing "https://github.com/gittools/gitversion/blob/main/src/GitVersion.Testing"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#005cbf,color:#005cbf
    classDef core fill:#d4edda,stroke:#155724,color:#155724
    classDef output fill:#ffe5b4,stroke:#cc5500,color:#cc5500
    classDef external fill:#e2e3e5,stroke:#6c757d,color:#6c757d
```
