Gradle Snapshot Plugin

Snapshot plugin for the Gradle build system.

License

License

Categories

Categories

Gradle Build Tools
GroupId

GroupId

com.pieceof8.gradle
ArtifactId

ArtifactId

gradle-snapshot-plugin
Last Version

Last Version

1.0.0
Release Date

Release Date

Type

Type

jar
Description

Description

Gradle Snapshot Plugin
Snapshot plugin for the Gradle build system.
Project URL

Project URL

http://github.com/PieceOf8/gradle-snapshot-plugin
Source Code Management

Source Code Management

http://github.com/PieceOf8/gradle-snapshot-plugin

Download gradle-snapshot-plugin

How to add to project

<!-- https://jarcasting.com/artifacts/com.pieceof8.gradle/gradle-snapshot-plugin/ -->
<dependency>
    <groupId>com.pieceof8.gradle</groupId>
    <artifactId>gradle-snapshot-plugin</artifactId>
    <version>1.0.0</version>
</dependency>
// https://jarcasting.com/artifacts/com.pieceof8.gradle/gradle-snapshot-plugin/
implementation 'com.pieceof8.gradle:gradle-snapshot-plugin:1.0.0'
// https://jarcasting.com/artifacts/com.pieceof8.gradle/gradle-snapshot-plugin/
implementation ("com.pieceof8.gradle:gradle-snapshot-plugin:1.0.0")
'com.pieceof8.gradle:gradle-snapshot-plugin:jar:1.0.0'
<dependency org="com.pieceof8.gradle" name="gradle-snapshot-plugin" rev="1.0.0">
  <artifact name="gradle-snapshot-plugin" type="jar" />
</dependency>
@Grapes(
@Grab(group='com.pieceof8.gradle', module='gradle-snapshot-plugin', version='1.0.0')
)
libraryDependencies += "com.pieceof8.gradle" % "gradle-snapshot-plugin" % "1.0.0"
[com.pieceof8.gradle/gradle-snapshot-plugin "1.0.0"]

Dependencies

compile (2)

Group / Artifact Type Version
org.tmatesoft.hg4j » hg4j Optional jar 1.0.0
org.eclipse.jgit : org.eclipse.jgit Optional jar 2.1.0.201209190230-r

test (2)

Group / Artifact Type Version
org.hamcrest : hamcrest-library jar 1.3
junit : junit jar 4.11

Project Modules

There are no modules declared in this project.

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

Versions

Version
1.0.0