lefou / mill-vcs-version

Mill plugin to derive a version from (last) git tag and edit state

Version Matrix

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

Build Status (GitHub Actions) Test Coverage (Codecov.io)

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


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_mill0.9:0.1.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.


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 that zero, the commit count will be padded to the given length

  • 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, e.g. removing a prefix "v"

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


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




0.7.0 - 0.8.0




0.6.0 - 0.6.3





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



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.


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.


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

mill-vsc-version 0.1.1 - 2020-01-21

  • Fixed handling of repos without any (previous) tag

mill-vsc-version 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.

mill-vsc-version 0.0.1 - 2020-06-22

  • Initial Release, intended for internal/test usage