SimpleBranchVersioning

A .NET source generator that derives version information from Git branch names.

Why use SimpleBranchVersioning?

• Zero configuration - Install the package and it just works
• Convention-based - Version format follows your branch naming (e.g., release/v1.2.3 becomes version 1.2.3)
• Automatic NuGet versioning - Package versions are set automatically based on the branch
• Compile-time generation - Version info is embedded as constants, no runtime Git dependencies

Installation

dotnet add package SimpleBranchVersioning

Usage

After installing the package, a static AppVersion class is automatically generated:

Console.WriteLine($"Version: {AppVersion.Version}");
Console.WriteLine($"Branch: {AppVersion.Branch}");
Console.WriteLine($"Commit: {AppVersion.CommitId}");

Version Format

Branch Pattern	Version	PackageVersion
release/v1.2.3	1.2.3	1.2.3+abc1234
release/1.2.3	1.2.3	1.2.3+abc1234
feature/login	feature.login.abc1234	0.0.0-feature.login+abc1234
main	main.abc1234	0.0.0-main+abc1234

Generated Class

public static class AppVersion
{
    public const string Version = "...";              // Display version
    public const string Branch = "...";               // Git branch name
    public const string CommitId = "...";             // Short commit ID
    public const string PackageVersion = "...";       // NuGet-compatible version
    public const string AssemblyVersion = "...";      // Assembly version (X.Y.Z.0)
    public const string FileVersion = "...";          // File version
    public const string InformationalVersion = "..."; // Full version with metadata
}

Configuration

MSBuild Properties

Property	Default	Description
SetPackageVersionFromBranch	true	Automatically set NuGet package version from branch
IncludeCommitIdMetadata	true	Include commit ID as build metadata in versions
GenerateVersionFile	false	Generate version.json file during build
SimpleBranchVersioning_Branch	(auto-detected)	Override branch name (useful for CI)

Custom Class Name and Namespace

[assembly: SimpleBranchVersioning.AppVersionConfig(
    Namespace = "MyApp.Versioning",
    ClassName = "BuildInfo")]

CI/CD Integration

For regular branch builds (push events), SimpleBranchVersioning works automatically - no configuration needed.

Pull Request Builds

CI systems usually check out PRs in a detached HEAD state, which results in version detached.<commit-id>. You can override the branch name using the SimpleBranchVersioning_Branch MSBuild property.

GitHub Actions example:

- uses: actions/checkout@v6

- name: Build
  run: dotnet build -p:SimpleBranchVersioning_Branch=${{ github.head_ref }}

For other CI systems, use your platform's branch variable with -p:SimpleBranchVersioning_Branch=<branch>.

Version File

Enable GenerateVersionFile to output version information during build:

<PropertyGroup>
    <GenerateVersionFile>true</GenerateVersionFile>
</PropertyGroup>

The file is written to $(OutputPath)/version.json and is included in dotnet publish output.

Analyzers

SimpleBranchVersioning includes built-in analyzers that provide build-time feedback about version detection and potential issues with branch names.

See AnalyzerReleases.Shipped.md for the list of available diagnostics.

Requirements

• .NET SDK 8.0 or later
• Git repository

License

This project is licensed under the MIT License - see the LICENSE file for details.