mix version

Automatically updates the version of Elixir projects:

• Updates the version number in mix.exs.
• Commits the changes.
• Creates an annotated git tag with the new version.
• Supports hooks to add additional changes, for instance updating a change log.

Installation

As a dependency

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

def deps do
  [
    {:mix_version, "~> 2.4", 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:

• The configuration of MixVersion from the config files is not supported anymore. This is to support MixVersion as a globally installed archive. When MixVersion is not listed in the dependencies, Elixir would warn if a project contains configuration for an unknown application.
• The new configuration is provided by listing a :versioning from the project/0 callback of the mix.exs file.
• The --git-only option was dropped. MixVersion will warn and prompt if some files are not checked in, allowing to fix those issues before any change is made to the mix.exs file and any commit/tag is created.
• Any unchecked change to the mix.exs file will prevent MixVersion to run.
• The :annotate option is now true by default, creating annotated tags.

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
  [
    annotate:   true,
    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 :annotate is set to false in configuration, you can use the --annotate CLI flag to force it to be true.

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.

-a, --annotate
      Create an annotated git tag.

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

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

-k, --tag-current
      Commit and tag with the current version. 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