Ecosyste.ms: Awesome

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

Awesome Lists | Featured Topics | Projects

https://github.com/manikmagar/git-versioner-maven-extension

Generate Maven project versions from git commit history. No more manual version management.
https://github.com/manikmagar/git-versioner-maven-extension

maven maven-extension maven-plugin versioning

Last synced: 3 months ago
JSON representation

Generate Maven project versions from git commit history. No more manual version management.

Awesome Lists containing this project

README 

        
= Git Versioner Maven Plugin

ifndef::env-github[:icons: font]

ifdef::env-github[]

:caution-caption: :fire:

:important-caption: :exclamation:

:note-caption: :paperclip:

:tip-caption: :bulb:

:warning-caption: :warning:

endif::[]

:toc: macro



image:https://img.shields.io/github/release/manikmagar/git-versioner-maven-plugin.svg[Release,link=https://github.com/manikmagar/git-versioner-maven-plugin/releases]

image:https://github.com/manikmagar/git-versioner-maven-plugin/workflows/build/badge.svg[Build Status,link=https://github.com/manikmagar/git-versioner-maven-plugin/actions]

image:https://img.shields.io/github/license/manikmagar/git-versioner-maven-plugin[GitHub]



Generate the semver version using the git commit history and automatically set it to maven pom.



No more manually modifying the pom.xml to decide on the versions.

You continue developing and adding commits to your project.

When it is time to release, add a commit with a message containing

a specific version keyword and watch the magic happen.



toc::[]



== How does it work?

This extension iterates over all the commit history and looks for a predefined keywords representing version changes.

It then computes the version number upto current commit.



The extension supports generating Semantic Versions `x.y.z` format. The format pattern is configurable to use

values such as Git hash, branch name etc.



See https://github.com/manikmagar/git-versioner-maven-extension-examples[manikmagar/git-versioner-maven-extension-examples]

 for examples of using this extension.



[#versionKeywords]

== What are version keywords?

*Version keywords* are the reserved words that describes which milestone of the release is this.



By default, extension supports following keywords -



- `[major]` - A Major version milestone Eg. 1.0.0 -> 2.0.0

- `[minor]` - A Minor version milestone Eg. 1.1.0 -> 1.2.

- `[patch]` - A Patch version milestone Eg. 1.1.1 -> 1.1.2



To change the keywords, see how to link:#versionKeywords_custom[Customize Version Keywords].



== How to configure?

This is a maven build core extension that can -



- Participate in maven build lifecycle

- Automatically set the building project's version

- No explicit mojo executions needed to set the version

- Project's POM remain unchanged



To use as a maven build extension,



Create (or modify) `extensions.xml` file in `${project.baseDir}/.mvn/`

to have the following entry -



NOTE: The artifact id is *git-versioner-maven-_extension_*.



..mvn/extensions.xml

[source,xml]

----



    

        com.github.manikmagar

        git-versioner-maven-extension

        ${latest-version-here}

    



----



See an example test project at link:git-versioner-maven-extension/src/test/resources/project-with-extension/[].



With just that configuration, next time your project runs any maven goals, you should see version from this module

is used by Maven reactor. Try running `mvn package` on your project.



== How to start with a different version?

It is possible that your project is already released with a certain version.

In that case, you can configure the initial version to start counting versions from.



You can add following properties to `.mvn/git-versioner.extensions.properties` file -



.Example configuration for initial version for extension mode

[source,properties]

----

gv.initialVersion.major=1

gv.initialVersion.minor=3

gv.initialVersion.patch=4

----



With above initial version configuration, the first version calculated by this extension will be -



- Major: *2.0.0*

- Minor: 1.*4.0*

- Patch: 1.3.*5*



== How do I increment version?

Now that you have extension configured, you can continue with your regular development.



When it is time to increment version, you may use one of the following three goals

to add an *_empty commit_* with appropriate link:#versionKeywords[Version Keyword] -



- `git-versioner:commit-major`: Adds a git commit with a commit message containing *Major* version keyword

- `git-versioner:commit-minor`: Adds a git commit with a commit message containing *Minor* version keyword

- `git-versioner:commit-patch`: Adds a git commit with a commit message containing *Patch* version keyword



CAUTION: Use `--non-recursive` flag when running commit goal in a multi-module maven project to avoid adding one commit per included module.



The default message pattern is `chore(release): [%k]` where `[%k]` is the keyword token.

To change the default message pattern, you could pass `-Dgv.commit.message=` argument when running the goal.



NOTE: When this extension is configured, it automatically makes `git-versioner` plugin goals available

with *NO* any additional configuration.



.Example commit patch with a custom message

[source, shell]

----

mvn git-versioner:commit-patch "-Dgv.commit.message=chore: [%k] release" --non-recursive

----



Off course, you can also add commits manually with appropriate version keywords.



.Manually adding a version commit

[source, shell]

----

git commit --allow-empty -m "chore: [] release" // <1>

----



<1> where `` can be one of these - major, minor, or patch.



== How to change the version pattern?



The default version pattern used is `major.minor.patch(-commit)` where `(-commit)` is skipped if commit count is 0.



This pattern can be canged by setting a property in `.mvn/git-versioner.extensions.properties`.



The following example will generate versions as `major.minor.patch+shorthash`, eg. `1.2.3+a5a29f8`.



.Example configuration for version pattern in extension mode

[source,properties]

----

gv.pattern.pattern=%M.%m.%p+%h

----



.Available Tokens for Version Pattern

|===

|Token |Description |Example



|%M

|Major Version

|**1**.y.z



|%m

|Minor Version

|x.**1**.z



|%p

|Patch Version

|x.y.**1**



|%c

|Commit count

|x.y.z-**4**



|([anything]%c)

|Non-Zero Commit count

|Given _%M.%m.%p(-%c)_

 with _%M=1_, _%m=2_, _%p=3_



when c == 0 -> _1.2.3_



when c > 0, = 5 -> _1.2.3-**5**_



|%b

|Branch name

|_%M.%m.%p+%b_ -> _1.2.3+**main**_



|%H

|Long Hash Ref

|_%M.%m.%p+%H_ -> _1.2.3+**b5f600c40f362d9977132e8bf7398d2cdc745c28**_



|%h

|Short Hash Ref

|_%M.%m.%p+%H_ -> _1.2.3+**a5a29f8**_

|===



[#versionKeywords_custom]

== How to customize version keywords?

The default link:#versionKeywords[version keywords] `[major]`, `[minor]`, and `[patch]` can be customized by overriding the configuration.



To use different keywords, you can add following properties to `.mvn/git-versioner.extensions.properties` file -



.Example configuration for initial version for extension mode

[source,properties]

----

gv.keywords.majorKey=[BIG]

gv.keywords.minorKey=[SMALL]

gv.keywords.patchKey=[FIX]

----



=== Use regex for version keywords

You can also use regex to match version keywords.

This is useful when you want to be sure that the version keyword will only be matched when it is the first word in the commit message.

So if for example you have a merge commit message which contains the messages of the merged commits, you can use a regex to match only the first commit message.



To use regex for version keywords, you can add following properties to `.mvn/git-versioner.extensions.properties` file -



.Example configuration for regex version keywords

----

gv.keywords.useRegex=true

gv.keywords.majorKey=^\\[major\\].*

gv.keywords.minorKey=^\\[minor\\].*

gv.keywords.patchKey=^\\[patch\\].*

----



== How to access generated version properties?

This extension adds all version properties to *Maven properties* during build cycle -



.Example of Injected maven properties (demo values)

[source, properties]

----

git-versioner.commitNumber=0

git-versioner.major=0

git-versioner.minor=0

git-versioner.patch=1

git-versioner.version=0.0.1

git.branch=main

git.hash=67550ad6a64fe4e09bf9e36891c09b2f7bdc52f9

git.hash.short=67550ad

----



You may use these properties in maven pom file, for example as `${git.branch}` to access git branch name.



== How to create Git tags?



You can use `git-versioner:tag` goal to create a git tag for current version in local git repository.



NOTE: This does not push tag to remote repository.



.Tag goal with default parameter values

[source,shell]

----

mvn git-versioner:tag \

  "-Dtag.failWhenTagExist=true" \

  "-Dtag.messagePattern=Release version %v" \

  "-Dtag.namePattern=v%v"

----



For Tag goal, it is possible to configure pom.xml to contain the git-versioner plugin with required execution configuration.



.Git Tag Goal with default configuration parameters

[source, xml]

----



    com.github.manikmagar

    git-versioner-maven-plugin

    

      

        tag

        

          tag

        

        

          true // <1>

          v%v  // <2>

          Release version %v // <3>

        

      

    



----



<1> If set to not fail, it will just log warning and skip tag creation.

<2> Tag name pattern to use. Default `v%v` will result in tags like `v1.2.3`.

<3> Tag message pattern to use. Default `Release version %v` will add tag message like `Release version 1.2.3`.



== Contributing



All contributions are welcome. Please see link:CONTRIBUTING.adoc[Contributing] guides.



== Acknowledgement

This is inspired from Gradle plugin https://github.com/toolebox-io/gradle-git-versioner[toolebox-io/gradle-git-versioner] that I have been using for my Gradle projects. This maven plugin is my attempt to get those auto-version capabilities into my Maven builds.