Gradle Snapshot Plugin

A Gradle plugin to generate build metadata from Source Control Management (SCM) tools.

The Snapshot Plugin is considered feature complete. It depends on the plugin API from Gradle 1.6 or greater and is compatible with Gradle 2.0.
Please report bugs and suggest new features on the issues page.

This plugin takes the most recent commit from the SCM repository and generates a .properties file containing this information. This file is created in the $buildDir folder with a configurable filename.

The plugin integrates with the Java and War plugins from Gradle's core plugins to make packaging the generated file output very easy (auto-managed).

This plugin recognises Git repositories (via the JGit library) and Mercurial repositories (via the Hg4j library). Support for other SCM repositories will be added upon request (or even better send us your pull request! =P), only SCMs that have a Java library to communicate with it's repository layout can be included.

This code is licensed under the Apache License v2.0. Documentation licensed under CC BY 3.0.

Usage

The plugin follows a convention-over-configuration approach to simplify usage of the plugin.

Minimal Example

To use the plugin add the following to your build.gradle script with Git SCM support:

buildscript {
  repositories {
    mavenCentral()
  }
  dependencies {
    classpath(
      [group: 'me.cmoz.gradle', name: 'gradle-snapshot-plugin', version: '2.0.2'])
  }
}

apply plugin: 'snapshot'

Full Example

A complete example including some configurable options for a Mercurial SCM repository:

buildscript {
  repositories {
    mavenCentral()
  }
  dependencies {
    classpath(
      [group: 'me.cmoz.gradle', name: 'gradle-snapshot-plugin', version: '2.0.2'])
  }
}

apply plugin: 'snapshot'

snapshot {
  filename   = 'snapshot.properties'          // default
  dateFormat = "dd.MM.yyyy '@' HH:mm:ss z"    // default
}

Build Environment Example

The plugin makes all the properties recorded in the snapshot.properties file also available at build time:

buildscript {
  repositories {
    mavenCentral()
  }
  dependencies {
    classpath(
      [group: 'me.cmoz.gradle', name: 'gradle-snapshot-plugin', version: '2.0.2'])
  }
}

apply plugin: 'snapshot'
apply plugin: 'java'

jar {
  dependsOn snapshot

  appendix project.ext.properties['commit.id.abbrev']
}

Real World Example

If you're not sure how to integrate this code into your build script have a look at the sample build.gradle.

Configuration

All of the configuration options for the plugins are:

snapshot {
  filename   = "snapshot.properties"          // default
  dateFormat = "dd.MM.yyyy '@' HH:mm:ss z"    // default
  verbose    = true
}

A full description of each of the options is as follows:

Name	Type	Description
filename	(string)	The name of the file that's generated by the Snapshot plugin. Defaults to snapshot.properties.
dateFormat	(string)	The date format used when generating the values for snapshot.commit.time and snapshot.build.time. This must be a SimpleDateFormat compatible string. Defaults to dd.MM.yyyy '@' HH:mm:ss z.
verbose	(boolean)	Enable verbose mode in the plugin, the properties recorded by the plugin are printed to stdout. Defaults to false.

Generated .properties file

The file generated by this plugin contains a snapshot of the information from the most recent commit made to the codebase. It's generated in the .properties format to make it easy to parse within application code. For example, it can be used to generate the build information required to display a commit id alongside a version number in the help dialog of an application.

The following properties are recorded:

commit.id.abbrev     = fd8c338
commit.user.email    = [email protected]
commit.message.full  = The full length of the commit message.
commit.id            = fd8c33821f02beb8ec47ae73256b64171ff5eaed
commit.message.short = A truncated form of the commit message.
commit.user.name     = Some User
build.user.name      = Another User
build.user.email     = [email protected]
branch               = branch-name
commit.time          = dd.MM.yyyy '@' HH:mm:ss z
build.time           = dd.MM.yyyy '@' HH:mm:ss z

Contribute

All contributions to the documentation and the codebase are very welcome. Send me your pull requests! :)

This plugin is written in Java and can be built using version 1.6 or greater of Gradle.

Thanks

Many thanks to the following developers for contributing to the codebase:

• @FrantaM