Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/novabyte/gradle-snapshot-plugin
A Gradle plugin to generate build metadata from Source Control Management (SCM) tools.
https://github.com/novabyte/gradle-snapshot-plugin
Last synced: about 2 months ago
JSON representation
A Gradle plugin to generate build metadata from Source Control Management (SCM) tools.
- Host: GitHub
- URL: https://github.com/novabyte/gradle-snapshot-plugin
- Owner: novabyte
- License: apache-2.0
- Created: 2012-03-08T20:48:35.000Z (over 12 years ago)
- Default Branch: master
- Last Pushed: 2015-02-23T17:42:10.000Z (over 9 years ago)
- Last Synced: 2024-02-07T20:39:26.829Z (5 months ago)
- Language: Java
- Homepage:
- Size: 331 KB
- Stars: 16
- Watchers: 5
- Forks: 4
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Lists
- awesome-gradle - gradle-snapshot-plugin - Generate build metadata from SCM tools. (Plugins / SCM)
README
Gradle Snapshot Plugin
======================
A [Gradle](http://gradle.org/) 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](https://github.com/novabyte/gradle-snapshot-plugin/issues) page.
This plugin takes the most recent commit from the SCM repository and generates a [`.properties`](http://en.wikipedia.org/wiki/.properties) file containing this information. This file is created in the `$buildDir` folder with a configurable filename.
The plugin integrates with the [Java](http://www.gradle.org/docs/current/userguide/java_plugin.html) and [War](http://gradle.org/docs/current/userguide/war_plugin.html) 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](http://eclipse.org/jgit/) library) and Mercurial repositories (via the [Hg4j](http://hg4j.com/) 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](http://www.apache.org/licenses/LICENSE-2.0). Documentation licensed under [CC BY 3.0](http://creativecommons.org/licenses/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:
```groovy
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:
```groovy
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:
```groovy
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`](https://github.com/novabyte/gradle-snapshot-plugin/tree/master/sample).
## Configuration
All of the configuration options for the plugins are:
```groovy
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:
```properties
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