How gittools/gitversion works
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)