JarCastingGradle 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 |
| dateFormat | (string) | The date format used when generating the values for Defaults to |
| verbose | (boolean) | Enable verbose mode in the plugin, the properties recorded by the plugin are printed to Defaults to |
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