View Source mix version (mix_version v2.2.0)

This module implements a mix task whose main purpose is to update the version number of an Elixir application, with extra steps such as committing a git tag.

This is a simple tool to automatically update the version number of an Elixir project in the mix.exs, commit the change and create and create a git tag based on the new version.

Check out version_tasks for a more versatile solution.

Installation

Although this tool can be set as a dependency in you mix projects, is is rather intended to be used as a globally available command line tool.

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 the tool should be used were implemented:

  • The configuration of the tool from the config files is not supported anymore. This is to support the tool as a globally installed archive. When mix_version 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, as the tool 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 the tool to run.
  • The :annotate option is now true by default, creating annotated tags.

Configuration

The configuration for v2 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
  [
    tag_prefix: "release-",
    commit_msg: "new version: %s",
    annotation: "tag release-%s created with mix_version",
    annotate: true
  ]
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.

Configuration can be overriden by command line options. For instance, if :annotate is set to true in configuration, you can use the --no-annotate CLI flag to force it to be false.

The following sample configuration is now unsupported and will be ignored.

import Config

# UNSUPPORTED AS OF v2.0.0
config :mix_version,
  tag_prefix: "release-",
  commit_msg: "new version: %s",
  annotation: "tag release-%s created with mix_version",
  annotate: true

Default configuration

annotate:   true
commit_msg: "new version %s"
annotation: "new version %s"
tag_prefix: "v"

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.

-M, --major        boolean. Bump to a new major version.
-m, --minor        boolean. Bump to a new minor version.
-p, --patch        boolean. Bump the patch version.
-a, --annotate     boolean. Create an annotated git tag.
-A, --annotation   string. Define the tag annotation message, with all '%s' replaced by the new VSN.
-c, --commit-msg   string. Define the commit message, with all '%s' replaced by the new VSN.
-n, --new-version  string. Set the new version number.
-x, --tag-prefix   string. Define the tag prefix.

When using the options to bump a part of the version, a pre-release tag will be dropped for a major or minor bump, whereas a patch bump will only remove this pre-release tag and keep the current patch number.

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

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

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

Usage

mix version [options]

Options

  • -a, --annotate - Create an annotated git tag.
  • -A, --annotation - Define the tag annotation message, with all '%s' replaced by the new VSN.
  • -c, --commit-msg - Define the commit message, with all '%s' replaced by the new VSN.
  • -i, --info - Only outputs the current version and stops. Ignores all other options.
  • -M, --major - Bump to a new major version.
  • -m, --minor - Bump to a new minor version.
  • -n, --new-version - Set the new version number.
  • -p, --patch - Bump the patch version.
  • -k, --tag-current - Commit and tag with the current version.
  • -x, --tag-prefix - Define the tag prefix.
  • --help - Displays this help.