{"id":24271486,"url":"https://github.com/sharpjs/subatomix.build.versioning.semantic","last_synced_at":"2026-02-22T14:21:08.631Z","repository":{"id":68403112,"uuid":"240306650","full_name":"sharpjs/Subatomix.Build.Versioning.Semantic","owner":"sharpjs","description":"Semi-automatic semantic versioning for .NET and MSBuild","archived":false,"fork":false,"pushed_at":"2024-07-29T21:51:26.000Z","size":227,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-18T10:35:29.858Z","etag":null,"topics":["dotnet","msbuild","semver","versioning"],"latest_commit_sha":null,"homepage":"","language":"PowerShell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"isc","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sharpjs.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGES.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-02-13T16:25:20.000Z","updated_at":"2024-07-29T21:50:30.000Z","dependencies_parsed_at":null,"dependency_job_id":"61f1e811-2cac-4fcc-a334-e0c590c43126","html_url":"https://github.com/sharpjs/Subatomix.Build.Versioning.Semantic","commit_stats":null,"previous_names":["sharpjs/sharp.build.versioning.semantic"],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sharpjs%2FSubatomix.Build.Versioning.Semantic","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sharpjs%2FSubatomix.Build.Versioning.Semantic/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sharpjs%2FSubatomix.Build.Versioning.Semantic/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sharpjs%2FSubatomix.Build.Versioning.Semantic/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sharpjs","download_url":"https://codeload.github.com/sharpjs/Subatomix.Build.Versioning.Semantic/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245517601,"owners_count":20628373,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["dotnet","msbuild","semver","versioning"],"created_at":"2025-01-15T17:45:59.348Z","updated_at":"2025-10-20T09:22:25.682Z","avatar_url":"https://github.com/sharpjs.png","language":"PowerShell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Subatomix.Build.Versioning.Semantic\n[![NuGet](https://img.shields.io/nuget/v/Subatomix.Build.Versioning.Semantic.svg)](https://www.nuget.org/packages/Subatomix.Build.Versioning.Semantic)\n[![NuGet](https://img.shields.io/nuget/dt/Subatomix.Build.Versioning.Semantic.svg)](https://www.nuget.org/packages/Subatomix.Build.Versioning.Semantic)\n\nSemi-automatic [SemVer2-compatible](https://semver.org/spec/v2.0.0.html)\nversioning for .NET and MSBuild.\n\nFeatures:\n- Generates SemVer2 versions from Git branches, pull requests, and tags.\n- Verifies that version-like Git tags match their code versions.\n\n## Status\n\nIn use by several projects.\n\n## Requirements\n\nThis package makes the following assumptions:\n\n- .NET [SDK-style](https://docs.microsoft.com/en-us/dotnet/core/project-sdk/overview)\n  project system\n- Git source control\n- Releases marked with Git tags like `v1.2.3` or `release/1.2.3-rc.1`  \n  (a configurable prefix followed by a valid [SemVer2](https://semver.org/spec/v2.0.0.html) version)\n\n## Usage\n\nAdd a reference to this package in your project file or in a\n[`Directory.Build.targets`](https://docs.microsoft.com/en-us/visualstudio/msbuild/customize-your-build#directorybuildprops-and-directorybuildtargets)\nfile.\n\n```xml\n\u003cItemGroup\u003e\n  \u003cPackageReference\n    Include=\"Subatomix.Build.Versioning.Semantic\"\n    Version=\"1.0.1\"\n    PrivateAssets=\"all\" /\u003e\n\u003c/ItemGroup\u003e\n```\n\nSet the version number in your project file or in a\n[`Directory.Build.props`](https://docs.microsoft.com/en-us/visualstudio/msbuild/customize-your-build#directorybuildprops-and-directorybuildtargets)\nfile.  Use the `VersionPrefix` MSBuild property only.\n\n```xml\n\u003cPropertyGroup\u003e\n  \u003cVersionPrefix\u003e1.2.3\u003c/VersionPrefix\u003e\n\u003c/PropertyGroup\u003e\n```\n\nPass the [git refspec](https://git-scm.com/book/en/v2/Git-Internals-The-Refspec)\ninto the build process using the `Branch` MSBuild property.\n\n```shell\ndotnet build -c Release -p:Branch=refs/heads/mybranch\n```\n\nThe build will generate a version like `1.2.3-mybranch.20201214.T154854Z` and\nset both the `Version` and `VersionSuffix` MSBuild properties automatically.\nTo use a custom build number instead of the default date/time-based one, pass\nthe number to the build process using the `Counter` MSBuild property.\n\n```shell\ndotnet build -c Release -p:Branch=refs/heads/mybranch -p:Counter=4567\n```\n\nThe build will generate the version `1.2.3-mybranch.b.4567`.\n\nTo build a custom pre-release or a final release, use a version-like Git tag.\n\n```shell\ndotnet build -c Release -p:Branch=refs/tags/release/1.2.3-beta -p:Counter=4567\n```\n\nThe build will generate the version `1.2.3-beta`.  When the Git tag looks like\na SemVer2 version, the build uses that version verbatim and does not append a\ntimestamp or a build number.\n\n#### Interaction With Build Servers\n\nTo communicate the generated version number to a build server, add one or\nmore of the following MSBuild properties to one of your project files.\n\n```xml\n\u003cPropertyGroup\u003e\n  \u003cSetAzurePipelinesBuildName\u003etrue\u003c/SetAzurePipelinesBuildName\u003e\n  \u003cSetGitHubActionsVersion\u003etrue\u003c/SetGitHubActionsVersion\u003e\n  \u003cSetTeamCityBuildNumber\u003etrue\u003c/SetTeamCityBuildNumber\u003e\n\u003c/PropertyGroup\u003e\n```\n\n#### Custom Version-Like Tag Prefix\n\nBy default, this package expects version-like Git tags to have a `release/`\nprefix.  To use a different prefix, override the `VersionTagPrefix` MSBuild\nproperty.  This can be useful if you prefer the `v` prefix.\n\n```xml\n\u003cPropertyGroup\u003e\n  \u003cVersionTagPrefix\u003ev\u003c/VersionTagPrefix\u003e\n\u003c/PropertyGroup\u003e\n```\n\nA custom prefix is useful to disambiguate the version-like Git tags of\nunrelated subprojects in a monorepo.\n\n```xml\n\u003cPropertyGroup\u003e\n  \u003cVersionTagPrefix\u003eMyProject/v\u003c/VersionTagPrefix\u003e\n\u003c/PropertyGroup\u003e\n```\n\n#### Version Stamping\n\nTODO\n\n## MSBuild Property Reference\n\n#### `Branch`\nThe full [git refspec](https://git-scm.com/book/en/v2/Git-Internals-The-Refspec)\nof the code being built.  The behavior of this package depends primarily on\nthe format of the refspec:\n\n- `refs/heads/foo`\n  - Recognized as a branch named `foo`.\n  - Sets the version suffix to `foo` followed by a build counter.\n- `refs/heads/foo/bar`\n  - Recognized as a branch named `foo/bar`.\n  - Sets the version suffix to `foo-bar` followed by a build counter.\n- `refs/pull/42`\n  - Recognized as pull request 42.\n  - Sets the version suffix to `pr.42` followed by a build counter.\n- `refs/tag/release/1.2.3-foo.42`\n  - Recognized as a version-like Git tag with the pre-release version\n    `1.2.3-foo.42`.\n  - Emits a build error if the `VersionPrefix` property does not match \n    the tag version, `1.2.3`.\n  - Sets the version suffix to `foo.42` followed by a build counter.\n  - The `release/` prefix is configurable.\n- `refs/tag/release/1.2.3`\n  - Recognized as a version-like Git tag with the release version `1.2.3`.\n  - Emits a build error if the `VersionPrefix` property does not match \n    the tag version, `1.2.3`.\n  - **Does not** set a version suffix or append a build counter.\n  - The `release/` prefix is configurable.\n- `something else entirely`\n  - Not recognized.\n  - Sets the version suffix to `something-else-entirely` followed by a\n    build counter.\n- empty or not set\n  - Sets the version suffix to `local`, without a build counter.  This\n    default is intended to ease local development.\n\n#### `Counter`\nAn arbitrary number to distinguish the current build from other builds of\nthe same refspec.  If not set, the build generates a date/time-based\ncounter of the form `yyyymmdd.ThhmmssZ` using the current UTC time.\n\n#### `StampOnBuild`\nTODO\n\n#### `SetAzurePipelinesBuildName`\nWhen `true`, the build outputs [magic text](https://docs.microsoft.com/en-us/azure/devops/pipelines/scripts/logging-commands?view=azure-devops#updatebuildnumber-override-the-automatically-generated-build-number)\nthat sets the name and `$(Build.BuildNumber)` [variable](https://docs.microsoft.com/en-us/azure/devops/pipelines/build/variables?view=azure-devops#build-variables-devops-services)\nof the current Azure DevOps pipeline run.\n\n#### `SetGitHubActionsVersion`\nWhen `true`, the build outputs [magic text](https://docs.github.com/en/free-pro-team@latest/actions/reference/workflow-commands-for-github-actions#setting-an-output-parameter)\nthat sets the `Version` [output parameter](https://docs.github.com/en/free-pro-team@latest/actions/reference/context-and-expression-syntax-for-github-actions#steps-context)\nof the current workflow step.\n\n#### `SetTeamCityBuildNumber`\nWhen `true`, the build outputs [magic text](https://www.jetbrains.com/help/teamcity/service-messages.html#Reporting+Build+Number)\nthat sets the [build number](https://www.jetbrains.com/help/teamcity/build-number.html)\nof the current TeamCity build.\n\n#### `VersionTagPrefix`\nThe prefix that identifies a version-like Git tag.  The default value is\n`release/`.\n\n\u003c!--\n  Copyright Subatomix Research Inc.\n  SPDX-License-Identifier: ISC\n--\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsharpjs%2Fsubatomix.build.versioning.semantic","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsharpjs%2Fsubatomix.build.versioning.semantic","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsharpjs%2Fsubatomix.build.versioning.semantic/lists"}