{"id":21313991,"url":"https://github.com/octopusdeploy/octoversion","last_synced_at":"2025-08-07T21:11:57.837Z","repository":{"id":205004011,"uuid":"289170470","full_name":"OctopusDeploy/OctoVersion","owner":"OctopusDeploy","description":"| Public |  .NET tool for determining version number based on the Git revision graph","archived":false,"fork":false,"pushed_at":"2025-01-21T22:21:24.000Z","size":420,"stargazers_count":3,"open_issues_count":1,"forks_count":5,"subscribers_count":10,"default_branch":"main","last_synced_at":"2025-07-02T15:05:04.282Z","etag":null,"topics":["public"],"latest_commit_sha":null,"homepage":null,"language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/OctopusDeploy.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-08-21T03:41:21.000Z","updated_at":"2025-01-21T22:20:28.000Z","dependencies_parsed_at":"2024-05-29T05:55:44.570Z","dependency_job_id":"1d7d0585-fc5b-48ca-bacd-f9a5c83f2b9d","html_url":"https://github.com/OctopusDeploy/OctoVersion","commit_stats":null,"previous_names":["octopusdeploy/octoversion"],"tags_count":470,"template":false,"template_full_name":null,"purl":"pkg:github/OctopusDeploy/OctoVersion","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OctopusDeploy%2FOctoVersion","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OctopusDeploy%2FOctoVersion/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OctopusDeploy%2FOctoVersion/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OctopusDeploy%2FOctoVersion/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/OctopusDeploy","download_url":"https://codeload.github.com/OctopusDeploy/OctoVersion/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OctopusDeploy%2FOctoVersion/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264923080,"owners_count":23683716,"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":["public"],"created_at":"2024-11-21T18:09:39.979Z","updated_at":"2025-07-12T01:30:59.154Z","avatar_url":"https://github.com/OctopusDeploy.png","language":"C#","readme":"[![feedz.io](https://img.shields.io/badge/endpoint.svg?url=https%3A%2F%2Ff.feedz.io%2Foctopus-deploy%2Fdependencies%2Fshield%2FNuke.OctoVersion%2Fstable\u0026label=Nuke.OctoVersion)](https://f.feedz.io/octopus-deploy/dependencies/packages/Nuke.OctoVersion/stable/download)\n\n# Welcome to OctoVersion\n\n## What is OctoVersion?\n\nOctoVersion is a dotnet tool for deriving a SemVer 2.0 version number based on a Git revision graph.\n\n## Getting started\n\nInstall the tool into the global tool registry:\n\n```\ndotnet tool install --global Octopus.OctoVersion.Tool\n```\n\nor into the local project's tool manifest:\n\n```\ndotnet tool install Octopus.OctoVersion.Tool\n```\n\nRun it against a local Git repository:\n\n```\ncd ~/code/my-app\noctoversion --CurrentBranch=main # if installed globally\ndotnet tool run octoversion --CurrentBranch=main # if installed locally\n```\n\nYou should see output that looks something like this:\n\n```\n[22:16:32 INF] Version is 0.0.5\n```\n\n## Integrating with build tools\n\n### Nuke\n\nAdd a reference to `OctoVersion.Tool` in your Nuke `_build` project. This can be done using the nuke command:\n\n```\nnuke :add-package Octopus.OctoVersion.Tool --version X.X.X\n```\n\nAdd a field marked with `[OctoVersion]` and it will be auto-populated:\n\n```c#\nusing Nuke.Common\nusing Nuke.Common.Git;\nusing Nuke.Common.Tools.OctoVersion;\nusing Serilog;\n\nclass Build : NukeBuild\n{\n     [GitRepository]\n     readonly GitRepository GitRepository;\n\n     string Branch =\u003e GitRepository.Branch;\n\n     // The Required Attribute will automatically throw an exception if the \n     // OctoVersionInfo parameter is not set due to an error or misconfiguration in Nuke.\n     [Required]\n     // 'Framework = \"net6.0\"' is only required for net6.0 apps.\n     [OctoVersion(UpdateBuildNumber = true, \n                  BranchParameter = nameof(Branch),\n                  Framework = \"net6.0\")]\n     readonly OctoVersionInfo OctoVersionInfo;\n     \n     Target PrintVersion =\u003e _ =\u003e _\n     .Executes(() =\u003e {\n                Log.Information($\"The version is {OctoVersion.MajorMinorBuild}\");\n     });\n}\n```\n\nTake a look at the Nuke [OctoVersionAttribute](https://github.com/nuke-build/nuke/blob/master/source/Nuke.Common/Tools/OctoVersion/OctoVersionAttribute.cs) for all available attribute properties. \n\n### Cake\n\n```csharp\n#module nuget:?package=Cake.DotNetTool.Module\u0026version=0.4.0\n#addin \"nuget:?package=Cake.OctoVersion\u0026version=0.3.63\"\n\n// The list below is to manually resolve NuGet dependencies to work around a bug in Cake's dependency loader.\n// Our intention is to remove this list again once the Cake bug is fixed.\n//\n// What we want:\n// #addin \"nuget:?package=Cake.OctoVersion\u0026version=0.0.138\u0026loaddependencies=true\"\n// (Note the loaddependencies=true parameter.)\n//\n// Our workaround:\n#addin \"nuget:?package=LibGit2Sharp\u0026version=0.26.2\"\n#addin \"nuget:?package=Serilog\u0026version=2.8.0.0\"\n#addin \"nuget:?package=Serilog.Settings.Configuration\u0026version=3.1.0.0\"\n#addin \"nuget:?package=Serilog.Sinks.Console\u0026version=3.0.1.0\"\n#addin \"nuget:?package=Serilog.Sinks.Literate\u0026version=3.0.0.0\"\n#addin \"nuget:?package=SerilogMetrics\u0026version=2.1.0.0\"\n#addin \"nuget:?package=Octopus.OctoVersion.Core\u0026version=0.3.63\"\n#addin \"nuget:?package=Cake.OctoVersion\u0026version=0.0.138\"\n#addin \"nuget:?package=Microsoft.Extensions.Primitives\u0026version=3.1.7\"\n#addin \"nuget:?package=Microsoft.Extensions.Configuration\u0026version=3.1.7.0\"\n#addin \"nuget:?package=Microsoft.Extensions.Configuration.Abstractions\u0026version=3.1.7.0\"\n#addin \"nuget:?package=Microsoft.Extensions.Configuration.Binder\u0026version=3.1.7.0\"\n#addin \"nuget:?package=Microsoft.Extensions.Configuration.CommandLine\u0026version=3.1.7.0\"\n#addin \"nuget:?package=Microsoft.Extensions.Configuration.EnvironmentVariables\u0026version=3.1.7.0\"\n#addin \"nuget:?package=Microsoft.Extensions.Configuration.FileExtensions\u0026version=3.1.0.0\"\n#addin \"nuget:?package=Microsoft.Extensions.Configuration.Json\u0026version=3.1.7\"\n#addin \"nuget:?package=Microsoft.Extensions.DependencyModel\u0026version=2.0.4.0\"\n#addin \"nuget:?package=Microsoft.Extensions.FileProviders.Abstractions\u0026version=3.1.0.0\"\n#addin \"nuget:?package=Microsoft.Extensions.FileProviders.Physical\u0026version=3.1.0.0\"\n\nusing Path = System.IO.Path;\nusing IO = System.IO;\nusing Cake.Common.Tools;\n\nvar target = Argument(\"target\", \"Default\");\nvar configuration = Argument(\"configuration\", \"Release\");\n\nif (!BuildSystem.IsRunningOnTeamCity) OctoVersionDiscoverLocalGitBranch(out _);\nOctoVersion(out var versionInfo);\n\nTask(\"Default\")\n    .IsDependentOn(\"Build\");\n\nTask(\"Build\")\n    .IsDependentOn(\"Restore\")\n    .Does(() =\u003e\n    {\n        DotNetCoreBuild(\"./source\", new DotNetCoreBuildSettings\n        {\n            Configuration = configuration,\n            NoRestore = true,\n            ArgumentCustomization = args =\u003e args.Append($\"/p:Version={versionInfo.FullSemVer} /p:InformationalVersion={versionInfo.FullSemVer}\"),\n            MSBuildSettings = new DotNetCoreMSBuildSettings\n            {\n                ArgumentCustomization = args =\u003e args.Append($\"/p:Version={versionInfo.FullSemVer} /p:InformationalVersion={versionInfo.FullSemVer}\")\n            }\n        });\n    });\n\nRunTarget(target);\n```\n### TeamCity\n\n```bash\noctoversion --CurrentBranch=main --OutputFormats:0=TeamCity\n```\n\n```\n##teamcity[buildNumber '0.0.12']\n##teamcity[setParameter name='env.OCTOVERSION_Major' value='0']\n##teamcity[setParameter name='OctoVersion.Major' value='0']\n##teamcity[setParameter name='env.OCTOVERSION_Minor' value='0']\n##teamcity[setParameter name='OctoVersion.Minor' value='0']\n##teamcity[setParameter name='env.OCTOVERSION_Patch' value='12']\n##teamcity[setParameter name='OctoVersion.Patch' value='12']\n##teamcity[setParameter name='env.OCTOVERSION_MajorMinorPatch' value='0.0.12']\n##teamcity[setParameter name='OctoVersion.MajorMinorPatch' value='0.0.12']\n##teamcity[setParameter name='env.OCTOVERSION_PreReleaseTag' value='']\n##teamcity[setParameter name='OctoVersion.PreReleaseTag' value='']\n##teamcity[setParameter name='env.OCTOVERSION_PreReleaseTagWithDash' value='']\n##teamcity[setParameter name='OctoVersion.PreReleaseTagWithDash' value='']\n##teamcity[setParameter name='env.OCTOVERSION_BuildMetadata' value='']\n##teamcity[setParameter name='OctoVersion.BuildMetadata' value='']\n##teamcity[setParameter name='env.OCTOVERSION_BuildMetadataWithPlus' value='']\n##teamcity[setParameter name='OctoVersion.BuildMetadataWithPlus' value='']\n##teamcity[setParameter name='env.OCTOVERSION_FullSemVer' value='0.0.12']\n##teamcity[setParameter name='OctoVersion.FullSemVer' value='0.0.12']```\n```\n\n### Environment variables\n\n```bash\noctoversion --CurrentBranch=main --OutputFormats:0=Environment\n```\n\n```\nOCTOVERSION_Major=0\nOCTOVERSION_Minor=0\nOCTOVERSION_Patch=5\nOCTOVERSION_MajorMinorPatch=0.0.5\nOCTOVERSION_PreReleaseTag=\nOCTOVERSION_PreReleaseTagWithDash=\nOCTOVERSION_BuildMetadata=\nOCTOVERSION_BuildMetadataWithPlus=\nOCTOVERSION_FullSemVer=0.0.5\n```\n\n### JSON\n\n```bash\noctoversion --CurrentBranch=main --OutputFormats:0=Json\n```\n\n```\n{\n  \"Major\": 0,\n  \"Minor\": 0,\n  \"Patch\": 5,\n  \"MajorMinorPatch\": \"0.0.5\",\n  \"PreReleaseTag\": \"\",\n  \"PreReleaseTagWithDash\": \"\",\n  \"BuildMetadata\": \"\",\n  \"BuildMetadataWithPlus\": \"\",\n  \"FullSemVer\": \"0.0.5\"\n}\n```\n\n## Configuration\n\nOctoVersion sources configuration from:\n\n1. The first, if any, `octoversion.json` file (lower case!) it finds walking up from the current directory.\n1. Environment variables prefixed with the OCTOVERSION_ prefix.\n1. Command-line parameters.\n\nwith the later sources overriding the earlier ones. The configuration syntax for each is as per the standard [.NET Core standard configuration](https://docs.microsoft.com/en-us/aspnet/core/fundamentals/configuration/) providers:\n\n- `octoversion.json` uses the [JSON Configuration Provider](https://docs.microsoft.com/en-us/aspnet/core/fundamentals/configuration/?view=aspnetcore-3.1#file-configuration-provider) in the same way that `appsettings.json` files do.\n    - Yes, this means that you can hook in a customer Serilog sink using `octoversion.json` if you like :)\n- Environment variables use the [Environment Variables Configuration Provider](https://docs.microsoft.com/en-us/aspnet/core/fundamentals/configuration/?view=aspnetcore-3.1#evcp).\n- Command-line variables use the [Command-line Configuration Provider](https://docs.microsoft.com/en-us/aspnet/core/fundamentals/configuration/?view=aspnetcore-3.1#command-line).\n\n## FAQ\n\n### Can't you figure out the branch I'm on? Why do I have to specify it?\n\nThis way, madness lies.\n\nIt's important to remember that _branches in Git are a lie_. Branches are nothing more than pointers to a commit. It's entirely possible (and very likely) that a commit will be reachable from many branches - or no branches, if you've checked out a commit and have a detached head.\n\nRather than attempting to guess (and sneakily getting the answer incorrect), OctoVersion requires you to tell it which branch you're on. All good build servers will provide this as an environment variable or other build parameter, and it's trivial to pass the information to OctoVersion.\n\nFor local versioning, it's always possible to set up a `bash`/`zsh` alias along these lines:\n\n```bash\nalias ov=\"octoversion --CurrentBranch=`git branch --show-current`\"\n```\n\n## Bumping Versions\n\nYou can bump major and minor version numbers using conventional commit messages.\n\nMajor bumps can be achieved using either of the following within one of the commits in your PR:\n```\n+semver: breaking\n+semver: major\n```\n\nMinor bumps can be achieved using either of the following within one of the commits in your PR:\n```\n+semver: feature\n+semver: minor\n```\n\nPatch bumps occur per-commit, and do not require specific messages to occur.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foctopusdeploy%2Foctoversion","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foctopusdeploy%2Foctoversion","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foctopusdeploy%2Foctoversion/lists"}