Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/lefou/mill-vcs-version

Mill plugin to derive a version from (last) git tag and edit state
https://github.com/lefou/mill-vcs-version

git mill mill-plugin scala vcs

Last synced: 3 months ago
JSON representation

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

Awesome Lists containing this project

README 

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

:version: 0.4.0

:mill-platform: 0.11

:project-home: https://github.com/lefou/mill-vcs-version

:toc:

:toc-placement: preamble



ifdef::env-github[]

image:https://github.com/lefou/mill-vcs-version/workflows/.github/workflows/build.yml/badge.svg["Build Status (GitHub Actions)", link="https://github.com/lefou/mill-vcs-version/actions"]

image:https://codecov.io/gh/lefou/mill-vcs-version/branch/main/graph/badge.svg[Test Coverage (Codecov.io), link="https://codecov.io/gh/lefou/mill-vcs-version"]

image:https://index.scala-lang.org/lefou/mill-vcs-version/de.tobiasroeser.mill.vcs.version/latest-by-scala-version.svg?platform=mill{mill-platform}["Latest version (Scaladex)", link="https://index.scala-lang.org/lefou/mill-vcs-version/de.tobiasroeser.mill.vcs.version"]

endif::[]



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

It may support other VCS as well.



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



[source,scala,subs="attributes,verbatim"]

----

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::{version}`

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

https://search.maven.org/artifact/de.tototec/de.tobiasroeser.mill.vcs.version_mill{mill-platform}_2.13[Maven Central].



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



.Mill Platform suffix

[options="header"]

|===

| mill version  | mill platform | suffix | example

| 0.11.x | 0.11 | `_mill0.11` | ```$ivy.`de.tototec::de.tobiasroeser.mill.vcs.version::{version}````

| 0.10.x | 0.10 | `_mill0.10` | ```$ivy.`de.tototec::de.tobiasroeser.mill.vcs.version::{version}````

| 0.9.3 - 0.9.9      | 0.9 | `_mill0.9` | ```$ivy.`de.tototec::de.tobiasroeser.mill.vcs.version_mill0.9:{version}````

| 0.7.0 - 0.8.0 | 0.7 | `_mill0.7` | ```$ivy.`de.tototec::de.tobiasroeser.mill.vcs.version_mill0.7:{version}````

| 0.6.0 - 0.6.3 | 0.6 | `_mill0.6` | ```$ivy.`de.tototec::de.tobiasroeser.mill.vcs.version_mill0.6:{version}````

|===



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



```yaml

      - 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 https://www.apache.org/licenses/LICENSE-2.0[Apache License, Version 2.0].



== About



mill::

  https://github.com/lihaoyi/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::

+

--

https://github.com/lefou/[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 https://github.com/lefou?utf8=%E2%9C%93&tab=repositories&q=topic%3Amill&type=&language=[several mill plugins].



If you like my work, please star it on GitHub. You can also support me via https://github.com/sponsors/lefou[GitHub Sponsors].

--



Contributing::

  If you found a bug or have a feature request, please open a {project-home}/issues[new issue on GitHub].

  I also accept {project-home}/pulls[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