mix version

hex.pm Version Build Status License

Automatically updates the version of Elixir projects:

Installation

As a dependency

You can install MixVersion as a regular dependency in your Elixir projects:

defp deps do
  [
    {:mix_version, "~> 2.6", only: [:dev, :test], runtime: false},
  ]
end

Installing globally

When managing multiple projects, it can be easier to install the mix task as an archive.

mix archive.install hex mix_version

Breaking changes in version 2

The v2 is a partial rewrite where most checks are run before attempting to make any modification for the project. A few changes to how MixVersion should be used were implemented:

Configuration

Configuration can be provided under :versioning from the project/0 callback of the project file:

# in mix.exs

def project do
  [
    app: :my_app,
    version: "1.2.3",
    # ...
    versioning: versioning()
  ]
end

defp versioning do
  [
    annotation: "new version %s",
    commit_msg: "new version %s",
    tag_prefix: "v"
  ]
end

In the commit message and annotation, any occurence of %s will be replaced by the new version number. The presence of %s is not mandatory.

This configuration is totally optional. The sample values above are the default values used by mix version.

Configuration can be overriden by command line options. For instance, if :tag_prefix is set to "release/" in configuration, you can use --tag-prefix v to create a v-prefixed tag instead.

Hooks

Hooks run once the new version is known, before mix.exs is updated and the changes are committed. They are listed under the :before_commit key of the :versioning configuration and run in order:

Functions must return :ok or {:error, reason}. The first error stops the command before mix.exs is updated and before anything is committed or tagged.

Example: Generating a changelog

This configuration regenerates CHANGELOG.md with git-cliff and adds it to the version commit:

defp versioning do
  [
    before_commit: [
      &gen_changelog/2,
      {:add, "CHANGELOG.md"}
    ]
  ]
end

defp gen_changelog(vsn, info) do
  args = ["cliff", "--tag", vsn, "--with-tag-message", info.annotation, "-o", "CHANGELOG.md"]

  case System.cmd("git", args, stderr_to_stdout: true) do
    {_, 0} -> IO.puts("Updated CHANGELOG.md with #{vsn}")
    {out, _} -> {:error, "Could not update CHANGELOG.md:\n\n #{out}"}
  end
end

The --with-tag-message flag gives the annotation of the tag being created to the changelog template as message. For older releases, git-cliff reads that message from the annotated tags themselves, so a full regeneration of the changelog keeps the text of every release. Render it in the body template of your cliff.toml:

body = """
## [{{ version | trim_start_matches(pat="v") }}]
{% if message and message is not starting_with("new version") %}
{{ message }}
{% endif %}
...
"""

The starting_with filter skips the default "new version X.Y.Z" annotation.

Example: Release notes

Write the introduction of the release in a file and pass it with --annotation-file. It becomes the tag annotation, and the hook above adds it to the changelog entry:

mix version --minor --annotation-file tmp/release-notes.md
git push --follow-tags

The tag annotation then holds the release notes. Once the tag exists, git cliff --latest renders the introduction followed by the list of changes, which you can publish as a GitHub release with the GitHub CLI:

gh release create v1.3.0 --notes "$(git cliff --latest --strip all)"

Usage

Call the command from within a mix project. With no options, you will be prompted for the new version number.

mix version [options]

Options

Versions managed by Elixir follow the MAJOR.MINOR.PATCH scheme, with optionnaly a pre-release tag as in 1.0.0-rc2.

-i, --info
      Only outputs the current version and stops. Ignores all other options.
      Defaults to false.

-M, --major
      Bump to a new major version. Defaults to false.

-m, --minor
      Bump to a new minor version. Defaults to false.

-p, --patch
      Bump the patch version. Defaults to false.

-n, --new-version <string>
      Set the new version number. Defaults to nil.

-c, --commit-msg <string>
      Define the commit message, with all '%s' replaced by the new VSN.

-A, --annotation <string>
      Define the tag annotation message, with all '%s' replaced by the new VSN.

-F, --annotation-file <string>
      Read the tag annotation message from the given file, with all '%s'
      replaced by the new VSN. Cannot be used with --annotation.

-x, --tag-prefix <string>
      Define the tag prefix.

-k, --tag-current
      Commit and tag with the current version. Defaults to false.

    --confirm
      Print the commit message and the tag to create, and ask for confirmation
      before making any change. Defaults to false.

    --help
      Displays this help.

When bumping a part of the version, pre-release tags are dropped. For a major or minor bump, the version number changes, but it remains the same with a patch bump..

Bump major:
  1.2.3      ->  2.0.0
  1.2.3-rc1  ->  2.0.0

Bump minor:
  1.2.3      ->  1.3.0
  1.2.3-rc1  ->  1.3.0

Bump patch:
  1.2.3      ->  1.2.4
  1.2.3-rc1  ->  1.2.3  # Still 1.2.3