google-java-format-gradle-plugin

google-java-format-gradle-plugin copied to clipboard

= google-java-format-gradle-plugin :release-version: 0.9 :default-google-java-format-version: 1.8 :snapshot-version: 0.9-SNAPSHOT

A https://github.com/gradle/gradle[Gradle] plugin that utilizes https://github.com/google/google-java-format[google-java-format] to format the Java source files in your Gradle project.

image:https://travis-ci.org/sherter/google-java-format-gradle-plugin.svg?branch=master["Build Status", link="https://travis-ci.org/sherter/google-java-format-gradle-plugin"]

== Quick Start

• Apply the plugin in your build script (follow https://plugins.gradle.org/plugin/com.github.sherter.google-java-format[these instructions] for Gradle versions below 2.1)

[source,groovy] [subs="attributes"]

plugins { id 'com.github.sherter.google-java-format' version '{release-version}' }

• Make sure you have defined a repository that contains version {default-google-java-format-version} of google-java-format

[source,groovy]

repositories { mavenCentral() }

• Execute the task googleJavaFormat to format all *.java files in the project

[source,shell]

$ ./gradlew goJF

• Execute the task verifyGoogleJavaFormat to verify that all *.java files are formatted properly

[source,shell]

$ ./gradlew verGJF

== Extended Usage

• The plugin adds the extension googleJavaFormat to your project. Adjust the variable toolVersion to use a specific version of google-java-format. You can even define SNAPSHOT versions, but make sure that you have added a repository to the project that contains this version (e.g. mavenLocal()). For plugin version {release-version} this value defaults to {default-google-java-format-version}. On every new release the default value will be updated to the latest version of google-java-format.

[source,groovy] [subs="attributes"]

googleJavaFormat { toolVersion = '1.1-SNAPSHOT' }

• Choose betweeen 'GOOGLE' (default) and 'AOSP' style by setting the style option:

[source,groovy]

googleJavaFormat { options style: 'AOSP' }

• The extension object allows you to configure the default inputs for all tasks related to this plugin. It provides the same methods as a https://docs.gradle.org/2.0/javadoc/org/gradle/api/tasks/SourceTask.html[SourceTask] to set these inputs. Initially, a https://docs.gradle.org/current/javadoc/org/gradle/api/file/FileTree.html[FileTree] that contains all *.java files in the project directory (and recursivly all subdirectories, excluding files in a (sub)project's buildDir) is added with one source method call. However, this initial value for the default inputs can be overwritten (using setSource), extended (using additional source calls) and/or further filtered (using include and/or exclude patterns, see https://docs.gradle.org/2.0/javadoc/org/gradle/api/tasks/util/PatternFilterable.html[Ant-style exclude patterns]). The chapter about https://docs.gradle.org/current/userguide/working_with_files.html[Working With Files] in the Gradle user guide might be worth reading.

[source,groovy] [subs="attributes"]

googleJavaFormat { source = sourceSets*.allJava source 'src/special_dir' include '/*.java' exclude '/Template.java' exclude 'src/test/template_' }

• All tasks are of type https://docs.gradle.org/2.0/javadoc/org/gradle/api/tasks/SourceTask.html[SourceTask] and can be configured accordingly. In addition to the default tasks googleJavaFormat and verifyGoogleJavaFormat you can define custom tasks if you like. The task type VerifyGoogleJavaFormat also implements the interface https://docs.gradle.org/2.0/javadoc/org/gradle/api/tasks/VerificationTask.html[VerificationTask].

[source,groovy]

import com.github.sherter.googlejavaformatgradleplugin.GoogleJavaFormat import com.github.sherter.googlejavaformatgradleplugin.VerifyGoogleJavaFormat

task format(type: GoogleJavaFormat) { source 'src/main' source 'src/test' include '/*.java' exclude '/*Template.java' }

task verifyFormatting(type: VerifyGoogleJavaFormat) { source 'src/main' include '**/*.java' ignoreFailures true }

If you set sources in a task (by calling setSource and/or source), the default inputs from the extension object are not added to the final set of sources to process. However, if you don't modify the sources in the task and only add include and/or exclude patterns, the default inputs are first added and then further filtered according the the patterns.

• An additional include filter can be applied on the command line at execution time by setting the <taskName>.include system property. All input files that remain after applying the filters in build.gradle also have to match at least one of the patterns in the comma separated list in order to be eventually processed by the task. Note that this only allows you to further reduce the number of processed files. You can not use this to add another include method call to a task. (See https://github.com/sherter/google-java-format-gradle-plugin/blob/master/contrib/pre-commit[contrib/pre-commit] for a useful application of this feature).

[source,shell]

$ ./gradlew verGJF -DverifyGoogleJavaFormat.include="*Foo.java,bar/Baz.java"

== Snapshots On every push to the master branch https://travis-ci.org/[Travis] runs the tests and, if all tests pass, publishes the built artifact to https://oss.sonatype.org/content/repositories/snapshots/[Sonatype's snapshots repository]. Use the following build script snippet for the current snapshot version:

[source,groovy] [subs="attributes"]

buildscript { repositories { maven { url 'https://oss.sonatype.org/content/repositories/snapshots/' } } dependencies { classpath 'com.github.sherter.googlejavaformatgradleplugin:google-java-format-gradle-plugin:{snapshot-version}' } }

apply plugin: 'com.github.sherter.google-java-format'