Current Version Current Version Release Build Static Badge

Git2SemVer

Git2SemVer is a Visual Studio and developer friendly Semantic Versioning framework for .NET solution and project versioning. It works the same with both Visual Studio and dotnet CLI builds. Every build, on both developer boxes and the build system, get traceable build numbering (no commit counting).

This tool is for teams that:

  • Can benefit from true Semantic Versioning.
  • Uses Conventional Commits to automatically generate change logs.
  • Uses branches to separate releasable code from feature or under development code (e.g: GitHub flow or GitFlow).
  • Only releases builds from a build system (or controlled host).
  • Wants to avoid custom build scripts, and tools, on a build system.
  • Uses Visual Studio as well as dotnet CLI.
  • Values full traceability for every build regardless if on a build system or an uncontrolled developer box (commit counts/depth will not do).
  • Needs unique versioning customisation that the built-in C# scripting may provide.

Quick introduction

You:

  • Mark a release's commit by adding a git tag like v1.2.3.
  • Use separate branches for building release and non-release commits.
  • Use Conventional Commit mesages like fix: fixed crash on shutdown to mark commits with fixes, features, and/or breaking changes.

Git2SemVer automatically, on every build, provides:

  • Semantic versioning:
    • File version
    • Assembly version
    • Informational version
    • Package version (NuGet package version)
    • Other MSBuild version properties
    • Pre-release identifier like alpha/beta/rc (from branch name)
  • Build number
  • Host adaptive version formating like:
    • Including machine name in semantic version metadata when building on a developer's box.
    • Different build number sources and formating on GitHub Workflow and TeamCity.

Git2SemVer also detects and executes an optional C# script. This script can change any part of the versioning.

It can be configured for any mix of solution versioning and individual project versioning without external build-time tools. No build system version generation steps are needed, keeps developer and build environments simple and aligned.

An example git workflow from a release 1.2.3 to the next release 2.0.0:

gitGraph
        commit id:"1.2.3+99"
        
        commit id:"1.2.3+100" tag:"1.2.3"
        branch feature/berry order: 1
        checkout feature/berry
        commit id:"1.2.3-beta.101"

        checkout main
        commit id:"1.2.3-alpha.102"
        branch feature/peach order: 3
        checkout feature/berry

        branch develop/berry order: 2
        checkout develop/berry
        commit id:"feat:berry 1.3.0-alpha.103"
        checkout feature/berry
        merge develop/berry id:"1.3.0-beta.104"
        checkout main
        merge feature/berry id:"1.3.0+105"

        checkout feature/peach
        commit id:"fix:bug1 1.2.3-beta.106"
        commit id:"feat!:peach 2.0.0-beta.107"
        checkout main
        merge feature/peach id:"2.0.0+108" tag:"v2.0.0"

        commit id:"2.0.1-beta.108"

Features


Conventional Commits

Use conventional commits to automate both changelog generation and get semantic versioning for free.

Visual Studio and .NET developer friendly

Versioning on every Visual Studio or dotnet CLI build without exernal tools. Just build.

Semmantic Versioning

Industry standard Semmantic Version compliance.

Supports initial development versioning.

Environment Parity

Visual Studio, VS Code, and dotnet CLI are all the same to Git2SemVer. Build system and developer environments all get versioning without custom build steps, tools, or scripts.

#

Build Numbering

Automatic build numbering on all developer boxes and build system builds.

Full traceability. Build height NOT used.

C# Scripting

No limits customisable by built-in C# scripting with a versioning API.

Build Host Adaptive Versioning

The versioning adapts according to the build host.

e.g: Automatically uses TeamCity build counter for build number and drops machine name metadata.

Git Workflow Agnostic

No Git workflow configuration required. It works the same for GitFlow and GitHub Flow.

TeamCity Integration

Automatic build system detection with server build number (label) updated with a build version specifically adapted for TeamCity.

GitHub Workflows

Built in support for builds using GitHub Actions.

Constructs build number from run and run attempt numbers and adapts the version for GitHub builds.

License

Git2SemVer uses the MIT license.

Acknowledgments

This project uses the following tools and libraries. Many thanks to those who created and manage them.

Edit this page