SimpleBranchVersioning 0.6.0

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

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

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.