Versionize

stop using weird build scripts to increment your nuget's version, use versionize!

Automatic versioning and CHANGELOG generation, using conventional commit messages.

how it works:

1. when you land commits on your main branch, select the Squash and Merge option (not required).
2. add a title and body that follows the Conventional Commits Specification.
3. when you're ready to release a nuget package:
   1. git checkout main; git pull origin main
   2. run versionize
   3. git push --follow-tags origin main
   4. dotnet pack
   5. dotnet nuget push

versionize does the following:

1. bumps the version in your .csproj file (based on your commit history)
2. uses conventional-changelog to update CHANGELOG.md
3. commits .csproj file and CHANGELOG.md
4. tags a new release

Installation

dotnet tool install --global Versionize

Usage

Usage: versionize [command] [options]

Options:
  -?|-h|--help                         Show help information.
  -v|--version                         Show version information.
  -w|--workingDir <WORKING_DIRECTORY>  Directory containing projects to version
  --configDir <CONFIG_DIRECTORY>       Directory containing the .versionize configuration file
  -d|--dry-run                         Skip changing versions in projects, changelog generation and git commit
  --skip-dirty                         Skip git dirty check
  -r|--release-as <VERSION>            Specify the release version manually
  --silent                             Suppress output to console
  --skip-commit                        Don't commit changes to the git repository
  --skip-tag                           Don't tag the release commit
  --skip-changelog                     Don't update the changelog
  -i|--ignore-insignificant-commits    Don't bump the version if no significant commits (fix, feat or BREAKING)
                                       are found
  --exit-insignificant-commits         Exits with a non zero exit code if no significant commits (fix, feat or
                                       BREAKING) are found
  --commit-suffix                      Suffix to be added to the end of the release commit message (e.g. [skip ci])
  -p|--pre-release                     Release as pre-release version with given pre release label.
  -a|--aggregate-pre-releases          Include all pre-release commits in the changelog since the last full version.
                                       Only applies when new version is stable (non pre-release).
  --find-release-commit-via-message    Use commit message instead of tag to find last release commit.
  --tag-only                           Don't read/write the version from/to project files. Depend on version tags only.
  --proj-name                          Name of a project defined in the configuration file (for monorepos)
  --first-parent-only-commits          Ignore commits beyond the first parent
  -s|--sign                            Sign the git commit and tag
  --tag-template <TAG_TEMPLATE>    Template for git tags, e.g. {name}/v{version}

Commands:
  init                                 Initializes versionize for single projects or monorepo setups
    --force                             Overwrite existing .versionize file if it exists
    --single                            Write a .versionize file even for single-project repositories
    --version-element <VERSION_ELEMENT> Version element to add or update in project files (default: Version)
    --tag-template <TAG_TEMPLATE>       Tag template to use for each project (default: {name}-v{version})
    --initial-version <VERSION>         Initial version to write when missing (default: 0.0.0)
    --skip-project-update               Do not modify project files; only generate .versionize
  inspect                              Prints the current version to stdout
  changelog                            Prints a given version's changelog to stdout
    -v|--version <VERSION>             The version to include in the changelog (defaults to latest version if not specified)
    -p|--preamble <PREAMBLE>           Text to display before the list of commits

Example:

versionize --workingDir ./src init --single

Supported commit types

Every commit should be in the form <type>[optional scope]: <description> for example fix(parser): remove colon from type and scope

• fix - will trigger a patch version increment in the next release
• feat - will trigger a minor version increment in the next release
• all other types - you can use any commit type but that commit type will not trigger a version increment in the next release

Breaking changes must contain a line prefixed with BREAKING CHANGE: to allow versionize recognizing a breaking change. Breaking changes can use any commit type.

Example

git commit -m "chore: update dependencies" -m "BREAKING CHANGE: this will likely break the interface"

Custom Commit Header Patterns

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.

To configure custom header patterns, create a .versionize file in your working directory with the following structure:

{
  "CommitParser": {
    "HeaderPatterns": [
      "^Merged PR \\\\d+: (?<type>\\w*)(?:\\((?<scope>.*)\\))?(?<breakingChangeMarker>!)?: (?<subject>.*)$",
      "^Pull Request \\\\d+: (?<type>\\w*)(?:\\((?<scope>.*)\\))?(?<breakingChangeMarker>!)?: (?<subject>.*)$"
    ]
  }
}

Example

If your team commits include messages like the following:

• Merged PR 123: fix(squash-azure-case): subject text #64
• Pull Request 11792: feat(azure-case): subject text

You 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.

The happy versioning walkthrough

Preparation

Create a new project with the dotnet cli

mkdir SomeProject
dotnet new classlib

Ensure that a <Version> element is contained in file SomeProject.csproj

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <Version>1.0.0</Version>
  </PropertyGroup>
</Project>

Using versionize

Now let's start committing and releasing

git init
...make some changes to "Class1.cs"
git add *
git commit -a -m "chore: initial commit"

versionize

Will 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.

...make some changes to "Class1.cs"
git commit -a -m "fix: something went wrong we need a bugfix release"

versionize

Will update CHANGELOG.md, add git tags and commit everything. Note that the version in SomeProject.csproj is now 1.0.1.

...make some changes to "Class1.cs"
git commit -a -m "feat: something really awesome coming in the next release"

versionize

Will update CHANGELOG.md, add git tags and commit everything. Note that the version in SomeProject.csproj is now 1.1.0.

...make some changes to "Class1.cs"
git commit -a -m "feat: a really cool new feature" -m "BREAKING CHANGE: the API will break. sorry"

versionize

Will update CHANGELOG.md, add git tags and commit everything. Note that the version in SomeProject.csproj is now 2.0.0 since versionize detected a breaking change since the commit note BREAKING CHANGE was used above.

Bumping Alternative Version Elements

In some scenarios, you may want to bump a different version element instead of the standard <Version> element in your project files. This can be useful when you want to track file versions independently from package versions, or when working with specific version properties.

To use this feature, ensure your project file contains the desired version element (e.g., <FileVersion> or <AssemblyVersion>):

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <FileVersion>1.0.0</FileVersion>
  </PropertyGroup>
</Project>

Configure this in your .versionize file as part of the project configuration:

{
  "projects": [
    {
      "name": "MyProject",
      "path": ".",
      "versionElement": "FileVersion"
    }
  ]
}

For single-project repositories (non-monorepos), you can also configure it at the root level:

{
  "projects": [
    {
      "path": ".",
      "versionElement": "FileVersion"
    }
  ]
}

When this option is specified, versionize will:

• Look for and bump the specified element (e.g., <FileVersion>) instead of <Version>
• Still create git tags and update the changelog as normal
• Use the specified element for determining the current and next version

Supported values include Version (default), FileVersion, AssemblyVersion, or any custom property name. Only alphanumeric and underscore characters are allowed.

Pre-releases

Versionize supports creating pre-release versions by using the --pre-release flag with a pre-release label, for example alpha.

The following workflow illustrates how pre-release workflows with versionize work.

> git commit -a -m "chore: initial commit"
> versionize
// Generates version v1.0.0

> git commit -a -m "feat: some feature"
> versionize --pre-release alpha
// Generates version v1.1.0-alpha.0

> git commit -a -m "feat: some additional feature"