<commit_before># gradle-git

A set of plugins to support Git in the Gradle build tool.

[![Build Status](https://travis-ci.org/ajoberstar/gradle-git.png?branch=master)](https://travis-ci.org/ajoberstar/gradle-git)

There are three primary use cases for these plugins:
* Publishing to a Github Pages website.  The `github-pages` plugin adds support
for publishing static files to the `gh-pages` branch of a Git repository.
* Managing your release process. The `grgit-release` plugin adds an opinionated
way to manage releases and comply with [Semantic Versioning](http://semver.org).
* General Git actions.  This plugin JAR depends on, and makes available,
[grgit](https://github.com/ajoberstar/grgit) which provides a Groovy API for
interacting with Git repositories.

For more information see the documentation in the next sections.

**API Documentation:**

* [Javadoc](http://ajoberstar.org/gradle-git/docs/javadoc)
* [Groovydoc](http://ajoberstar.org/gradle-git/docs/groovydoc)

Credit goes to [<NAME>](https://github.com/pledbrook) for the initial
idea for the `github-pages` plugin.

Thanks to [<NAME>](https://github.com/zafarkhaja) for the very helpful
[java-semver](https://github.com/zafarkhaja/java-semver) library.

## Adding the Plugins

Add the following lines to your build to use the `gradle-git` plugins.

    buildscript {
      repositories {
        // jcenter()
        mavenCentral()
      }
      dependencies {
        classpath 'org.ajoberstar:gradle-git:<version>'
      }
    }

See the Release Notes at the bottom of this README for the available versions.

## Using Grgit

For freeform access to a Git repository, you only need the dependency on
`gradle-git`, no additional plugins need to be applied. Import the `grgit`
package and start using a repository.

```groovy
import org.ajoberstar.grgit.*

ext.repo = Grgit.open(project.file('.'))

version = "1.0.0-${repo.head().abbreviatedId}"

task tagRelease << {
  repo.tag.add {
    name = version
    message = "Release of ${version}"
  }
}
```

For details on the available methods/properties see the API docs of
[Grgit](http://ajoberstar.org/grgit/docs/groovydoc/org/ajoberstar/grgit/Grgit.html).
Examples of how to use each operation are provided there.

### Authentication

Grgit provides multiple ways to authenticate with remote repositories. If using hardcoded credentials, it is suggested to use the system properties rather than including them in the repository.

See Grgit's [AuthConfig](http://ajoberstar.org/grgit/docs/groovydoc/org/ajoberstar/grgit/auth/AuthConfig.html) docs for information on the
various authentication options.

Methods that produce a `Grgit` instance, which includes `clone`, `init`, and `open`, all take a `Credentials` instance if
you want to provide hardcoded credentials programmatically.

## github-pages

```groovy
apply plugin: 'github-pages'

githubPages {
  repoUri = '...'
  pages {
    from javadoc.outputs.files
  }
}
```

See the [GithubPagesPluginExtension](http://ajoberstar.org/gradle-git/docs/groovydoc/org/ajoberstar/gradle/git/ghpages/GithubPagesPluginExtension.html) docs for information on the defaults.

The plugin adds a single `publishGhPages` task that will clone the
repository, copy in the files in the `pages` `CopySpec`, add all of
the changes, commit, and push back to the remote.

## grgit-release

### Other Options for Gradle Release Plugins

Before describing this plugins functionality I want to point out the other plugins available (that I'm aware of):

* [townsfolk/gradle-release](https://github.com/townsfolk/gradle-release) - designed to work like the Maven Release
plugin. If that's what you're looking for this is your best option.
* [ari/gradle-release-plugin](https://github.com/ari/gradle-release-plugin/) - Seems purely oriented around versioning
the release and tagging it. Versions are generated dynamically based on current branch or tag.
* [stianh/gradle-release-plugin](https://github.com/stianh/gradle-release-plugin) - Similar approach (and created before)
the `ari` plugin. However, as of `4/13/14` it hasn't had any commits in 9 months.

### Approach of grgit-release

The `grgit-release` plugin is intended to be opinionated, and I am not trying to meet all needs. The core principles of
this plugin are:

* [Semantic versioning](http://semver.org) is the ideal way to version code (for most use cases).
* A Git repository contains enough information to be able to build useful version numbers that comply with semver, with
limited direction from the user. **The version should not need to be hardcoded into the source code.**

The general functionality involves:

1. Inferring the desired version based on the nearest tagged version(s) (similar to `git describe`) and the users input
of the **scope** of the changes being made and what **stage** of development they are in.
1. Ensuring all changes in the repository have been committed.
1. Ensuring there aren't any commits in the upstream branch that haven't been merged yet.
1. Validating that there have been commits since the nearest version. (Don't re-release with a different version.)
1. Optionally, checking all Java/Groovy files for @since tags. If they exist, ensure that they match a version that has
been tagged in the repository or the version that was just inferred.
1. Execute whatever release tasks the user specified in the plugin configuration. (e.g. `build`, `publishToRepo`)
1. Optionally, tag the release. Can be configured to only tag certain types of versions. (e.g. only `final` and `rc`)
1. Push changes in current branch to the remote. If a tag was made it will also be pushed.

### Applying the Plugin

Only the `grgit` property is mandatory. `releaseTasks` should be filled in if
you want the code built or published. Everything else has defaults, as noted
below.

```groovy
apply plugin: 'grgit-release'

import org.ajoberstar.grgit.*

release {
  grgit = Grgit.open(project.file('.'))
  remote = 'upstream' // default is 'origin'
  prefixTagNameWithV = false // default is true
  releaseTasks = ['build', 'publishGhPages', 'bintrayUpload'] // defaults to []
  enforceSinceTags = true // default is false

  version {
    untaggedStages = ['alpha'] // default is ['dev']
    taggedStages = ['beta'] // default is ['milestone', 'rc']<commit_msg>Fix #71 Update readme for qualified plugins ids.<commit_after># gradle-git

A set of plugins to support Git in the Gradle build tool.

[![Build Status](https://travis-ci.org/ajoberstar/gradle-git.png?branch=master)](https://travis-ci.org/ajoberstar/gradle-git)

There are three primary use cases for these plugins:
* Publishing to a Github Pages website.  The `org.ajoberstar.github-pages` plugin adds support
for publishing static files to the `gh-pages` branch of a Git repository.
* Managing your release process. The `org.ajoberstar.grgit-release` plugin adds an opinionated
way to manage releases and comply with [Semantic Versioning](http://semver.org).
* General Git actions.  This plugin JAR depends on, and makes available,
[grgit](https://github.com/ajoberstar/grgit) which provides a Groovy API for
interacting with Git repositories.

For more information see the documentation in the next sections.

**API Documentation:**

* [Javadoc](http://ajoberstar.org/gradle-git/docs/javadoc)
* [Groovydoc](http://ajoberstar.org/gradle-git/docs/groovydoc)

Credit goes to [<NAME>](https://github.com/pledbrook) for the initial
idea for the `org.ajoberstar.github-pages` plugin.

Thanks to [<NAME>](https://github.com/zafarkhaja) for the very helpful
[java-semver](https://github.com/zafarkhaja/java-semver) library.

## Adding the Plugins

Add the following lines to your build to use the `gradle-git` plugins.

    buildscript {
      repositories {
        // jcenter()
        mavenCentral()
      }
      dependencies {
        classpath 'org.ajoberstar:gradle-git:<version>'
      }
    }

See the Release Notes at the bottom of this README for the available versions.

## Using Grgit

For freeform access to a Git repository, you only need the dependency on
`gradle-git`, no additional plugins need to be applied. Import the `grgit`
package and start using a repository.

```groovy
import org.ajoberstar.grgit.*

ext.repo = Grgit.open(project.file('.'))

version = "1.0.0-${repo.head().abbreviatedId}"

task tagRelease << {
  repo.tag.add {
    name = version
    message = "Release of ${version}"
  }
}
```

For details on the available methods/properties see the API docs of
[Grgit](http://ajoberstar.org/grgit/docs/groovydoc/org/ajoberstar/grgit/Grgit.html).
Examples of how to use each operation are provided there.

### Authentication

Grgit provides multiple ways to authenticate with remote repositories. If using hardcoded credentials, it is suggested to use the system properties rather than including them in the repository.

See Grgit's [AuthConfig](http://ajoberstar.org/grgit/docs/groovydoc/org/ajoberstar/grgit/auth/AuthConfig.html) docs for information on the
various authentication options.

Methods that produce a `Grgit` instance, which includes `clone`, `init`, and `open`, all take a `Credentials` instance if
you want to provide hardcoded credentials programmatically.

## org.ajoberstar.github-pages

```groovy
apply plugin: 'org.ajoberstar.github-pages'

githubPages {
  repoUri = '...'
  pages {
    from javadoc.outputs.files
  }
}
```

See the [GithubPagesPluginExtension](http://ajoberstar.org/gradle-git/docs/groovydoc/org/ajoberstar/gradle/git/ghpages/GithubPagesPluginExtension.html) docs for information on the defaults.

The plugin adds a single `publishGhPages` task that will clone the
repository, copy in the files in the `pages` `CopySpec`, add all of
the changes, commit, and push back to the remote.

## org.ajoberstar.grgit-release

### Other Options for Gradle Release Plugins

Before describing this plugins functionality I want to point out the other plugins available (that I'm aware of):

* [townsfolk/gradle-release](https://github.com/townsfolk/gradle-release) - designed to work like the Maven Release
plugin. If that's what you're looking for this is your best option.
* [ari/gradle-release-plugin](https://github.com/ari/gradle-release-plugin/) - Seems purely oriented around versioning
the release and tagging it. Versions are generated dynamically based on current branch or tag.
* [stianh/gradle-release-plugin](https://github.com/stianh/gradle-release-plugin) - Similar approach (and created before)
the `ari` plugin. However, as of `4/13/14` it hasn't had any commits in 9 months.

### Approach of org.ajoberstar.grgit-release

The `org.ajoberstar.grgit-release` plugin is intended to be opinionated, and I am not trying to meet all needs. The core principles of
this plugin are:

* [Semantic versioning](http://semver.org) is the ideal way to version code (for most use cases).
* A Git repository contains enough information to be able to build useful version numbers that comply with semver, with
limited direction from the user. **The version should not need to be hardcoded into the source code.**

The general functionality involves:

1. Inferring the desired version based on the nearest tagged version(s) (similar to `git describe`) and the users input
of the **scope** of the changes being made and what **stage** of development they are in.
1. Ensuring all changes in the repository have been committed.
1. Ensuring there aren't any commits in the upstream branch that haven't been merged yet.
1. Validating that there have been commits since the nearest version. (Don't re-release with a different version.)
1. Optionally, checking all Java/Groovy files for @since tags. If they exist, ensure that they match a version that has
been tagged in the repository or the version that was just inferred.
1. Execute whatever release tasks the user specified in the plugin configuration. (e.g. `build`, `publishToRepo`)
1. Optionally, tag the release. Can be configured to only tag certain types of versions. (e.g. only `final` and `rc`)
1. Push changes in current branch to the remote. If a tag was made it will also be pushed.

### Applying the Plugin

Only the `grgit` property is mandatory. `releaseTasks` should be filled in if
you want the code built or published. Everything else has defaults, as noted
below.

```groovy
apply plugin: 'org.ajoberstar.grgit-release'

import org.ajoberstar.grgit.*

release {
  grgit = Grgit.open(project.file('.'))
  remote = 'upstream' // default is 'origin'
  prefixTagNameWithV = false // default is true
  releaseTasks = ['build', 'publishGhPages', 'bintrayUpload'] // defaults to []
  enforceSinceTags = true // default is false

  version {
    untaggedStages = ['alpha'] // default is ['dev']
    taggedStages = ['beta'] // default is ['milestone', 'rc']
{'fraction_non_alphanumeric': 0.09625333124314156, 'fraction_numerical': 0.0028217588963787427, 'mean_word_length': 4.291995022812111, 'pattern_counts': {'":': 0, '<': 13, '<?xml version=': 0, '>': 9, 'https://': 18, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '846488', 'n_tokens_mistral': 3736, 'n_tokens_neox': 3543, 'n_words': 1500}