lefou / mill-vcs-version   0.4.0

Apache License 2.0 GitHub

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

Scala versions: 2.13 2.12
Mill plugins: 0.11 0.10 0.9 0.7 0.6

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


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


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




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

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