code54 / buildversion-plugin

A maven plugin that extracts current build information from git projects
34 stars 9 forks source link

buildversion-maven-plugin

This is a maven plugin that extracts current build information from git projects, including: the latest commit hash, timestamp, most recent tag, number of commits since most recent tag. It also implements a "follow first parent" flavor of git describe (see "About git-describe" below for details).

Similar in intent to buildnumber-maven-plugin, this plugin sets Maven project properties intended to be used in later phases of the Maven lifecycle. You may use this to include build version information on property files, manifests and generated sources.

Usage

Simply add buildversion-plugin to your pom, executing the set-properties goal. Example:

  ...
  <build>
    <plugins>
      <plugin>
        <groupId>com.code54.mojo</groupId>
        <artifactId>buildversion-plugin</artifactId>
        <version>1.0.3</version>
        <executions>
          <execution>
            <goals><goal>set-properties</goal></goals>
          </execution>
        </executions>
      </plugin>
  ...

By default, the plugin runs on Maven's initialize phase. Any plugin running after that phase will see the following properties:

Note: buildversion-plugin is currently hosted at the oss.sonatype.org maven repository, and may depend on artifacts on the Clojars repository. You'd need to add these repos to your settings.xml or your project pom.xml. Example:

  <pluginRepositories>
    <pluginRepository>
      <id>sonatype-releases</id>
      <url>http://oss.sonatype.org/content/repositories/releases</url>
    </pluginRepository>
    <pluginRepository>
      <id>clojars.org</id>
      <url>http://clojars.org/repo</url>
    </pluginRepository>

    <!-- If you want to try SNAPSHOT versions, you need Sonatype's snapshots repo: -->
    <pluginRepository>
      <id>sonatype-snapshots</id>
      <url>http://oss.sonatype.org/content/repositories/snapshots</url>
    </pluginRepository>
  </pluginRepositories>

Configuration Parameters

Property Default Description
gitCmd git Name for 'git' executable to use. You may specify an absolute pathname or a command in you "PATH".
tstampFormat yyyyMMddHHmmss Specify a custom format for the `build-tstamp` property. Use the pattern syntax defined by Java's SimpleDateFormat
customProperties - Optional. A Clojure snippet of code you may specify in order to modify or create new properties. The code must evaluate to a Map. The name of the keys in the Map become Maven properties on the project. For convenience, for each `build-*` property you have a local variable with the same name already defined for you. See below for an example.

Example:

  <plugin>
    <groupId>com.code54.mojo</groupId>
    <artifactId>buildversion-plugin</artifactId>
    <version>1.0.3</version>
    <executions>
      <execution>
        <goals><goal>set-properties</goal></goals>
        <configuration>
          <!-- use only the day for the timestamp -->
          <tstampFormat>yyyy-MM-dd</tstampFormat>

          <!-- Define a new project property 'build-tag-lowercase', based on 'build-tag'
               Note how 'build-tag' is available to the script as a local variable. -->
          <customProperties>
            { :build-tag-lowercase (clojure.string/lower-case build-tag) }
          </customProperties>
        </configuration>
      </execution>
    </executions>
  </plugin>

About git-describe

Before writing this plugin, I used to rely on a simple script which called git describe to obtain a descriptive version number including most recent tag and commits since such a tag.

Unfortunately, the logic behind git describe searches for the closest tag back in history following all parent commits on merges. This means it may select tags you originally put on another branch. So, if you are working on a development branch and merge back a fix made on a release branch, calling git describe on the development branch may shield a description that includes a tag you placed on the release branch.

Until git describe accepts a --first-parent argument to prevent this problem, this plugin implements its own logic, which basically relies on git log --first-parent to traverse history on the current "line of development".

Reference:

Future

Some ideas:

FAQ

Acknowledgments

Thanks to Hugo Duncan for his work on clojure-maven and accepting my defmojo addition. He did the heavy-lifting to integrate Clojure with Maven and Plexus.

License

Licensed under the Eclipse Public License. Copyright 2012 Fernando Dobladez & Code54 S.A. (http://code54.com)