{"id":25611243,"url":"https://github.com/versionize/versionize","last_synced_at":"2026-05-09T01:30:23.149Z","repository":{"id":39757796,"uuid":"150849526","full_name":"versionize/versionize","owner":"versionize","description":"Automatic versioning and CHANGELOG generation, with semver and conventional commits for dotnet","archived":false,"fork":false,"pushed_at":"2024-10-25T11:31:44.000Z","size":365,"stargazers_count":295,"open_issues_count":16,"forks_count":46,"subscribers_count":9,"default_branch":"master","last_synced_at":"2024-10-25T17:17:18.470Z","etag":null,"topics":["changelog","dotnet-cli","dotnet-core","git","semantic-release","semantic-versioning"],"latest_commit_sha":null,"homepage":"","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/versionize.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","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":"2018-09-29T09:40:15.000Z","updated_at":"2024-10-24T14:11:16.000Z","dependencies_parsed_at":"2022-07-20T13:32:42.750Z","dependency_job_id":"5d41ef91-4e9b-40b4-b600-a10466c592f8","html_url":"https://github.com/versionize/versionize","commit_stats":{"total_commits":164,"total_committers":14,"mean_commits":"11.714285714285714","dds":0.5365853658536586,"last_synced_commit":"02797afb5531174c53b14c7c0866cbf04c29a973"},"previous_names":[],"tags_count":40,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/versionize%2Fversionize","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/versionize%2Fversionize/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/versionize%2Fversionize/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/versionize%2Fversionize/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/versionize","download_url":"https://codeload.github.com/versionize/versionize/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":240100531,"owners_count":19747688,"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":["changelog","dotnet-cli","dotnet-core","git","semantic-release","semantic-versioning"],"created_at":"2025-02-21T23:01:34.260Z","updated_at":"2026-05-09T01:30:23.083Z","avatar_url":"https://github.com/versionize.png","language":"C#","funding_links":[],"categories":["C\\#","C#"],"sub_categories":[],"readme":"# Versionize\n\n[![Coverage Status](https://coveralls.io/repos/versionize/versionize/badge.svg?branch=)](https://coveralls.io/r/versionize/versionize?branch=master)\n[![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-yellow.svg)](https://conventionalcommits.org)\n\n\u003e stop using weird build scripts to increment your nuget's version, use `versionize`!\n\nAutomatic versioning and CHANGELOG generation, using [conventional commit messages](https://conventionalcommits.org).\n\n_how it works:_\n\n1. when you land commits on your `main` branch, select the _Squash and Merge_ option (not required).\n2. add a title and body that follows the [Conventional Commits Specification](https://conventionalcommits.org).\n3. when you're ready to release a nuget package:\n    1. `git checkout main; git pull origin main`\n    2. run `versionize`\n    3. `git push --follow-tags origin main`\n    4. `dotnet pack`\n    5. `dotnet nuget push`\n\n`versionize` does the following:\n\n1. bumps the version in your `.csproj` file (based on your commit history)\n2. uses [conventional-changelog](https://github.com/conventional-changelog/conventional-changelog) to update _CHANGELOG.md_\n3. commits `.csproj` file and _CHANGELOG.md_\n4. tags a new release\n\n## Installation\n\n```bash\ndotnet tool install --global Versionize\n```\n\n## Usage\n\n```bash\nUsage: versionize [command] [options]\n\nOptions:\n  -?|-h|--help                         Show help information.\n  -v|--version                         Show version information.\n  -w|--workingDir \u003cWORKING_DIRECTORY\u003e  Directory containing projects to version\n  --configDir \u003cCONFIG_DIRECTORY\u003e       Directory containing the .versionize configuration file\n  -d|--dry-run                         Skip changing versions in projects, changelog generation and git commit\n  --skip-dirty                         Skip git dirty check\n  -r|--release-as \u003cVERSION\u003e            Specify the release version manually\n  --silent                             Suppress output to console\n  --skip-commit                        Don't commit changes to the git repository\n  --skip-tag                           Don't tag the release commit\n  --skip-changelog                     Don't update the changelog\n  -i|--ignore-insignificant-commits    Don't bump the version if no significant commits (fix, feat or BREAKING)\n                                       are found\n  --exit-insignificant-commits         Exits with a non zero exit code if no significant commits (fix, feat or\n                                       BREAKING) are found\n  --commit-suffix                      Suffix to be added to the end of the release commit message (e.g. [skip ci])\n  -p|--pre-release                     Release as pre-release version with given pre release label.\n  -a|--aggregate-pre-releases          Include all pre-release commits in the changelog since the last full version.\n                                       Only applies when new version is stable (non pre-release).\n  --find-release-commit-via-message    Use commit message instead of tag to find last release commit.\n  --tag-only                           Don't read/write the version from/to project files. Depend on version tags only.\n  --proj-name                          Name of a project defined in the configuration file (for monorepos)\n  --first-parent-only-commits          Ignore commits beyond the first parent\n  -s|--sign                            Sign the git commit and tag\n\nCommands:\n  inspect                              Prints the current version to stdout\n  changelog                            Prints a given version's changelog to stdout\n    -v|--version \u003cVERSION\u003e             The version to include in the changelog (defaults to latest version if not specified)\n    -p|--preamble \u003cPREAMBLE\u003e           Text to display before the list of commits\n```\n\n## Supported commit types\n\nEvery commit should be in the form\n`\u003ctype\u003e[optional scope]: \u003cdescription\u003e`\nfor example\n`fix(parser): remove colon from type and scope`\n\n* fix - will trigger a patch version increment in the next release\n* feat - will trigger a minor version increment in the next release\n* all other types - you can use any commit type but that commit type will not trigger a version increment in the next release\n\nBreaking changes **must** contain a line prefixed with `BREAKING CHANGE:` to allow versionize recognizing a breaking change. Breaking changes can use any commit type.\n\n**Example**\n\n```bash\ngit commit -m \"chore: update dependencies\" -m \"BREAKING CHANGE: this will likely break the interface\"\n```\n\n## Custom Commit Header Patterns\n\n`versionize` supports custom commit header patterns for parsing commit messages. This is particularly useful when your team uses commit messages that differ from the conventional commits format.\n\nTo configure custom header patterns, create a `.versionize` file in your working directory with the following structure:\n\n```json\n{\n  \"CommitParser\": {\n    \"HeaderPatterns\": [\n      \"^Merged PR \\\\\\\\d+: (?\u003ctype\u003e\\\\w*)(?:\\\\((?\u003cscope\u003e.*)\\\\))?(?\u003cbreakingChangeMarker\u003e!)?: (?\u003csubject\u003e.*)$\",\n      \"^Pull Request \\\\\\\\d+: (?\u003ctype\u003e\\\\w*)(?:\\\\((?\u003cscope\u003e.*)\\\\))?(?\u003cbreakingChangeMarker\u003e!)?: (?\u003csubject\u003e.*)$\"\n    ]\n  }\n}\n```\n\n### Example\n\nIf your team commits include messages like the following:\n\n- `Merged PR 123: fix(squash-azure-case): subject text #64`\n- `Pull Request 11792: feat(azure-case): subject text`\n\nYou can use the above configuration to ensure these commit messages are parsed correctly. `versionize` will extract the relevant type, scope, and subject information to include them in the changelog and determine version increments.\n\n\n## The happy versioning walkthrough\n\n### Preparation\n\nCreate a new project with the dotnet cli\n\n```bash\nmkdir SomeProject\ndotnet new classlib\n```\n\nEnsure that a \u0026lt;Version\u0026gt; element is contained in file SomeProject.csproj\n\n```xml\n\u003cProject Sdk=\"Microsoft.NET.Sdk\"\u003e\n  \u003cPropertyGroup\u003e\n    \u003cVersion\u003e1.0.0\u003c/Version\u003e\n  \u003c/PropertyGroup\u003e\n\u003c/Project\u003e\n```\n\n### Using versionize\n\nNow let's start committing and releasing\n\n```bash\ngit init\n...make some changes to \"Class1.cs\"\ngit add *\ngit commit -a -m \"chore: initial commit\"\n\nversionize\n```\n\nWill add a CHANGELOG.md, add git tags and commit everything. Note that the version in `SomeProject.csproj` will not change since this is your first release with `versionize`.\n\n```bash\n...make some changes to \"Class1.cs\"\ngit commit -a -m \"fix: something went wrong we need a bugfix release\"\n\nversionize\n```\n\nWill update CHANGELOG.md, add git tags and commit everything. Note that the version in `SomeProject.csproj` is now `1.0.1`.\n\n```bash\n...make some changes to \"Class1.cs\"\ngit commit -a -m \"feat: something really awesome coming in the next release\"\n\nversionize\n```\n\nWill update CHANGELOG.md, add git tags and commit everything. Note that the version in `SomeProject.csproj` is now `1.1.0`.\n\n```bash\n...make some changes to \"Class1.cs\"\ngit commit -a -m \"feat: a really cool new feature\" -m \"BREAKING CHANGE: the API will break. sorry\"\n\nversionize\n```\n\nWill update CHANGELOG.md, add git tags and commit everything. Note that the version in `SomeProject.csproj` is now `2.0.0` since\nversionize detected a breaking change since the commit note `BREAKING CHANGE` was used above.\n\n### Pre-releases\n\nVersionize supports creating pre-release versions by using the `--pre-release` flag with a pre-release label, for example `alpha`.\n\nThe following workflow illustrates how pre-release workflows with versionize work.\n\n```shell\n\u003e git commit -a -m \"chore: initial commit\"\n\u003e versionize\n// Generates version v1.0.0\n\n\u003e git commit -a -m \"feat: some feature\"\n\u003e versionize --pre-release alpha\n// Generates version v1.1.0-alpha.0\n\n\u003e git commit -a -m \"feat: some additional feature\"\n\u003e versionize --pre-release alpha\n// Generates version v1.1.0-alpha.1\n\n\u003e git commit -a -m \"feat: some breaking feature\" -m \"BREAKING CHANGE: This is a breaking change\"\n\u003e versionize --pre-release alpha\n// Generates version v2.0.0-alpha.0\n\n\u003e versionize\n// Generates version v2.0.0\n```\n\n### Aggregated pre-releases changelog\n\nBy default, each commit message only appears in the release it was introduced. When using the pre-release feature\nthis can result in a fragmented changelog. For example, when promoting to a full release the user has to browse\nthrough all the pre-release sections to see what's included.\n\n```\nv1.0.0-alpha.0\n- featA\nv1.0.0-alpha.1\n- featB\nv1.0.0\n```\n\nSo to get around that you can pass the `--aggregate-pre-releases` flag\n\n```\nversionize --pre-release alpha\nversionize --pre-release alpha\nversionize --aggregate-pre-releases\n```\n\nto get output like the following\n\n```\nv1.0.0-alpha.0\n- featA\nv1.0.0-alpha.1\n- featB\nv1.0.0\n- featA\n- featB\n```\n\nThis also works together with the `pre-release` option\n\n`versionize --pre-release alpha --aggregate-pre-releases`\n\n### Skip pre-release tags\n\nSome developers may prefer not to tag pre-releases. Here's an example of how to achieve that:\n\n```\nversionize --pre-release alpha --skip-tag\nversionize --pre-release alpha --skip-tag --find-release-commit-via-message\n...\n```\n\n`find-release-commit-via-message` is necessary because Versionize uses git tags by default to determine the current version. Without a git tag, the way we determine which commits get included in the changelog is by searching for the last commit message that starts with _\"chore(release):\"_. \n\n## Configuration\n\nYou can configure `versionize` either by creating a `.versionize` JSON file the working directory.\n\nAny of the command line parameters accepted by `versionize` can be provided via configuration file leaving out any `-`. For example `skip-dirty` can be provided as `skipDirty` in the configuration file. \nThe `.versionize` configuration file is deserialized into a `FileConfig.cs` object behind the scenes.\n\nChangelog customization can only be done via a `.versionize` file. The following is an example configuration:\n\n```json\n{\n  \"changelog\": {\n    \"header\": \"My Changelog\",\n    \"includeAllCommits\": true,\n    \"sections\": [\n      {\n        \"type\": \"feat\",\n        \"section\": \"✨ Features\",\n        \"hidden\": false\n      },\n      {\n        \"type\": \"fix\",\n        \"section\": \"🐛 Bug Fixes\",\n        \"hidden\": true\n      },\n      {\n        \"type\": \"perf\",\n        \"section\": \"🚀 Performance\",\n        \"hidden\": false\n      }\n    ]\n  }\n}\n```\n\nBecause `IncludeAllCommits` is true and the _fix_ section is hidden, fix commits will appear in the a section titled \"Other\".\n\n## Developing\n\nWant to do a PR and not care about setting up your development environment?\n\n[![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)](https://gitpod.io/#https://github.com/versionize/versionize)\n\nTo get prettier test outputs run `dotnet test` with prettier test logger\n\n```bash\ndotnet test --logger prettier\n```\n\n## Roadmap\n\n* [] Signed release commits\n* [] Command to print out changelog entry since last release (as opposed to writing to a file)\n* [] Tag prefix config (for non mono-repos)\n* [] Add support for bumping a Unity project version\n* [] Improve documentation\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fversionize%2Fversionize","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fversionize%2Fversionize","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fversionize%2Fversionize/lists"}