mill-vcs-version - Derive a version from Version Control

Mill plugin to derive a version from (last) git tag and edit state. It may support other VCS as well.

Table of Contents

Quickstart
Formatting options
Download
Caveats and Known Issues
- Limited git history in CI / Github Actions
License
About
Releases / Changelog

Quickstart

To use a git-derived version for publishing, all you need is to use VcsVersion.vcsState target. VcsVersion is an external mill module and as such can be used out of the box without further configuration.

import mill._
import mill.scalalib._
import mill.define._

// Load the plugin from Maven Central via ivy/coursier
import $ivy.`de.tototec::de.tobiasroeser.mill.vcs.version::0.4.1`
import de.tobiasroeser.mill.vcs.version.VcsVersion

object main extends JavaModule with PublishModule {
  override def publishVersion: T[String] = VcsVersion.vcsState().format()
}

Formatting options

The formatted version is base on

the latest git tag
the count of commits since the latest tag
the difference between the latest commit and the actual local state (changes or new files)

The format is highly customizable.

{git-tag}{commit-count-sep}{commit-count}{revision-sep}{revision-hash}{dirty-dep}{dirty-hash}

The format method has the following options:

noTagFallback: String = "0.0.0" - will be used when no tag was found
countSep: String = "-" - will be printed before the commit count when it is greater than zero
commitCountPad: Byte = 0 - if greater than zero, the commit count will be padded to the given length; a negative value results in never adding the commit count
revSep: String = "-" - will be printed before the revision hash if it is not a tagged revision
revHashDigits: Int = 6 - the number of digits to be used for the revision hash
dirtySep: String = "-DIRTY" - will be printed before the dirty hash if the local repository is in modified state
dirtyHashDigits: Int = 8 - the number of digits to be used for the dirty hash
tagModifier: String ⇒ String - allows to modify the git tag (By default this strips a leading v if one exists. e.g. v1.2.3 → 1.2.3)
untaggedSuffix: String = "" - will append the given string at the end of the version when the current revision is not tagged (e.g. use with `"-SNAPSHOT" to publish to Maven Snapshot repositories)

When used with its defaults, the outcome is identical to the version scheme used by Mill.

Download

You can download binary releases from Maven Central.

Please make sure to use the correct mill platform suffix matching your used mill version.

Table 1. Mill Platform suffix

mill version	mill platform	suffix	example
0.11.x - 0.12.x	0.11	`_mill0.11`	$ivy.`de.tototec::de.tobiasroeser.mill.vcs.version::0.4.1`
0.10.x	0.10	`_mill0.10`	$ivy.`de.tototec::de.tobiasroeser.mill.vcs.version::0.4.1`
0.9.3 - 0.9.9	0.9	`_mill0.9`	$ivy.`de.tototec::de.tobiasroeser.mill.vcs.version_mill0.9:0.4.1`
0.7.0 - 0.8.0	0.7	`_mill0.7`	$ivy.`de.tototec::de.tobiasroeser.mill.vcs.version_mill0.7:0.4.1`
0.6.0 - 0.6.3	0.6	`_mill0.6`	$ivy.`de.tototec::de.tobiasroeser.mill.vcs.version_mill0.6:0.4.1`

Caveats and Known Issues

Limited git history in CI / Github Actions

If you witness confusing behavior in a CI environment, it’s likely due to limited git history.

E.g. on Github, the default setup for action/checkout fetches only 50 commit back from the current version. That means, once your last tag is older than that, you will get strange version numbers, probably starting with 0.0.0.

So, in your CI setup, make sure to:

git checkout the complete history
git checkout all tags

For Github Actions, make sure all instances of action/checkout use the following setup.

      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
          # next line is redundant as it's the default
          fetch-tags: true

License

This project is published under the Apache License, Version 2.0.

About

Mill: Mill is a Scala-based open source build tool. In my opinion the best build tool for the JVM. It is fast, reliable and easy to understand.
Me: I’m a professional software developer and love to write and use open source software. I’m actively developing and maintaining Mill as well as several Mill plugins.

If you like my work, please star it on GitHub. You can also support me via GitHub Sponsors.
Contributing: If you found a bug or have a feature request, please open a new issue on GitHub. I also accept pull requests on GitHub.

Releases / Changelog

0.4.1 - 2024-12-11

Made VcsVersion.calcVcsState public

0.4.0 - 2023-06-07

Support Mill 0.11
Dependency updates: Scala 2.13.11 / 2.12.18
Silence stderr output from git

0.3.1 - 2023-04-26

Added support for Mill 0.11.0-M8
Dependency updates: scala 2.13.10 / 2.12.17
Internal improvements

0.3.0 - 2022-09-28

Support omitting the commit count
Don’t fail for projects not under version control
Added VcsState.vcs field to check for the current used version control system, if any
Commit to EarlySemVer version scheme
Updated dependencies and tools

0.2.0 - 2022-08-09

Version tags starting with a v-prefix are now properly stripped by default.

0.1.4 - 2022-01-17

Added support for mill 0.10.x

0.1.3 - 2022-01-14

For proper Mill 0.10 support, please use 0.1.4 or newer.

Added support for mill 0.10.0

0.1.2 - 2021-09-18

Added support for mill 0.10.0-M2
Improved error handling

0.1.1 - 2021-01-21

Fixed handling of repos without any (previous) tag

0.1.0 - 2020-12-01

Support for mill API 0.9.3
Introduce a new artifact name suffix (_mill0.9 for mil 0.9.3) to support multiple mill API versions.

0.0.1 - 2020-06-22

Initial Release, intended for internal/test usage

lefou / mill-vcs-version 0.4.1