formatter:format

Full name:

net.revelc.code.formatter:formatter-maven-plugin:2.23.0:format

Description:

A Maven plugin mojo to format Java source code using the Eclipse code formatter.

Mojo parameters allow customizing formatting by specifying the config XML file, line endings, compiler version, and source code locations. Reformatting source files is avoided using an sha512 hash of the content, comparing to the original hash to the hash after formatting and a cached hash.

Attributes:

  • Requires a Maven project to be executed.
  • The goal is thread-safe and supports parallel builds.
  • Binds by default to the lifecycle phase: process-sources.

Required Parameters

Name Type Since Description
<compilerCompliance> String - Java compiler compliance version.
Default value is: 1.8.
User property is: maven.compiler.source.
<compilerSource> String - Java compiler source version.
Default value is: 1.8.
User property is: maven.compiler.source.
<compilerTargetPlatform> String - Java compiler target version.
Default value is: 1.8.
User property is: maven.compiler.target.
<configCssFile> String - File or classpath location of a properties file to use in css formatting.
Default value is: formatter-maven-plugin/ph-css/css.properties.
User property is: configcssfile.
<configFile> String - File or classpath location of an Eclipse code formatter configuration xml file to use in formatting.
Default value is: formatter-maven-plugin/eclipse/java.xml.
User property is: configfile.
<configHtmlFile> String - File or classpath location of a properties file to use in html formatting.
Default value is: formatter-maven-plugin/jsoup/html.properties.
User property is: confightmlfile.
<configJsFile> String - File or classpath location of an Eclipse code formatter configuration xml file to use in formatting.
Default value is: formatter-maven-plugin/eclipse/javascript.xml.
User property is: configjsfile.
<configJsonFile> String - File or classpath location of a properties file to use in json formatting.
Default value is: formatter-maven-plugin/jackson/json.properties.
User property is: configjsonfile.
<configXmlFile> String - File or classpath location of a properties file to use in xml formatting.
Default value is: formatter-maven-plugin/eclipse/xml.properties.
User property is: configxmlfile.
<encoding> String 0.3 The file encoding used to read and write source files. When not specified and sourceEncoding also not set, default is platform file encoding.
User property is: project.build.sourceEncoding.
<lineEnding> LineEnding 0.2.0 Sets the line-ending of files after formatting. Valid values are:
  • "AUTO" - Use line endings of current system
  • "KEEP" - Preserve line endings of files, default to AUTO if ambiguous
  • "LF" - Use Unix and Mac style line endings
  • "CRLF" - Use DOS and Windows style line endings
  • "CR" - Use early Mac style line endings

Default value is: AUTO.
User property is: lineending.
<sourceDirectory> File - Project's source directory as specified in the POM.
Default value is: ${project.build.sourceDirectory}.
User property is: sourceDirectory.
<testSourceDirectory> File - Project's test source directory as specified in the POM.
Default value is: ${project.build.testSourceDirectory}.
User property is: testSourceDirectory.

Optional Parameters

Name Type Since Description
<cachedir> File 2.12.1 Projects cache directory.

This file is a hash cache of the files in the project source. It can be preserved in source code such that it ensures builds are always fast by not unnecessarily writing files constantly. It can also be added to gitignore in case startup is not necessary. It further can be redirected to another location.

When stored in the repository, the cache if run on cross platforms will display the files multiple times due to line ending differences on the platform.

The cache itself has been part of formatter plugin for a long time but was hidden in target directory and did not survive clean phase when it should. This is not intended to be clean in that way as one would want as close to a no-op as possible when files are already all formatted and/or have not been otherwise touched. This is used based off the files in the project so it is as much part of the source as any other file is.

The cache can become invalid for any number of reasons that this plugin can't reasonably detect automatically. If you rely on the cache and make any changes to the project that could conceivably make the cache invalid, or if you notice that files aren't being reformatted when they should, just delete the cache and it will be rebuilt.


Default value is: ${project.build.directory}.
User property is: formatter.cachedir.
<directories> File[] 0.4 Location of the Java source files to format. Defaults to source main and test directories if not set. Deprecated in version 0.3. Reintroduced in 0.4.
<excludes> String[] 0.3 List of fileset patterns for Java source locations to exclude from formatting. Patterns are relative to the project source and test source directories. When not specified, there is no default exclude.
User property is: formatter.excludes.
<includeResources> boolean 2.22.0 When set to true, the resources for the project are included in formatting. This includes both the main and test resources.

The included/excluded patterns for this plugin are honored as well as the included/excluded patterns from the resource itself.


Default value is: false.
User property is: formatter.includeResources.
<includes> String[] 0.3 List of fileset patterns for Java source locations to include in formatting. Patterns are relative to the project source and test source directories. When not specified, the default include is **/*.java
User property is: formatter.includes.
<javaExclusionPattern> String 2.13 A java regular expression pattern that can be used to exclude some portions of the java code from being reformatted.

This can be useful when using DSL that embeds some kind of semantic hierarchy, where users can use various indentation level to increase the readability of the code. Those semantics are ignored by the formatter, so this regex pattern can be used to match certain portions of the code so that they will not be reformatted.

An example is the Apache Camel java DSL which can be used in the following way:

	from("seda:a").routeId("a")
			.log("routing at ${routeId}")
			.multicast()
				.to("seda:b")
				.to("seda:c")
			.end()
			.log("End of routing");

In the above example, the except can be skipped by the formatter by defining the following property in the formatter xml configuration:

  <javaExclusionPattern>\b(from\([^;]*\.end[^;]*?\)\));</javaExclusionPattern>

User property is: formatter.java.exclusion_pattern.
<removeTrailingWhitespace> boolean 2.17.0 When set to true, remove trailing whitespace on all lines after the formatter has finished.

Default to 'true' since 2.18.0


Default value is: true.
User property is: formatter.removeTrailingWhitespace.
<skipCssFormatting> boolean - Whether the css formatting is skipped.
Default value is: false.
User property is: formatter.css.skip.
<skipFormatting> boolean 0.5 Whether the formatting is skipped.
Default value is: false.
User property is: formatter.skip.
Alias is: skip.
<skipFormattingCache> boolean 2.23.0 Whether the formatting cache is skipped.
Default value is: false.
User property is: formatter.cache.skip.
<skipHtmlFormatting> boolean - Whether the html formatting is skipped.
Default value is: false.
User property is: formatter.html.skip.
<skipJavaFormatting> boolean - Whether the java formatting is skipped.
Default value is: false.
User property is: formatter.java.skip.
<skipJsFormatting> boolean - Whether the javascript formatting is skipped.
Default value is: false.
User property is: formatter.js.skip.
<skipJsonFormatting> boolean - Whether the json formatting is skipped.
Default value is: false.
User property is: formatter.json.skip.
<skipXmlFormatting> boolean - Whether the xml formatting is skipped.
Default value is: false.
User property is: formatter.xml.skip.
<useEclipseDefaults> boolean - Use eclipse defaults when set to true for java and javascript.
Default value is: false.
User property is: formatter.useEclipseDefaults.

Parameter Details

<cachedir>

Projects cache directory.

This file is a hash cache of the files in the project source. It can be preserved in source code such that it ensures builds are always fast by not unnecessarily writing files constantly. It can also be added to gitignore in case startup is not necessary. It further can be redirected to another location.

When stored in the repository, the cache if run on cross platforms will display the files multiple times due to line ending differences on the platform.

The cache itself has been part of formatter plugin for a long time but was hidden in target directory and did not survive clean phase when it should. This is not intended to be clean in that way as one would want as close to a no-op as possible when files are already all formatted and/or have not been otherwise touched. This is used based off the files in the project so it is as much part of the source as any other file is.

The cache can become invalid for any number of reasons that this plugin can't reasonably detect automatically. If you rely on the cache and make any changes to the project that could conceivably make the cache invalid, or if you notice that files aren't being reformatted when they should, just delete the cache and it will be rebuilt.

  • Type: java.io.File
  • Since: 2.12.1
  • Required: No
  • User Property: formatter.cachedir
  • Default: ${project.build.directory}

<compilerCompliance>

Java compiler compliance version.
  • Type: java.lang.String
  • Required: Yes
  • User Property: maven.compiler.source
  • Default: 1.8

<compilerSource>

Java compiler source version.
  • Type: java.lang.String
  • Required: Yes
  • User Property: maven.compiler.source
  • Default: 1.8

<compilerTargetPlatform>

Java compiler target version.
  • Type: java.lang.String
  • Required: Yes
  • User Property: maven.compiler.target
  • Default: 1.8

<configCssFile>

File or classpath location of a properties file to use in css formatting.
  • Type: java.lang.String
  • Required: Yes
  • User Property: configcssfile
  • Default: formatter-maven-plugin/ph-css/css.properties

<configFile>

File or classpath location of an Eclipse code formatter configuration xml file to use in formatting.
  • Type: java.lang.String
  • Required: Yes
  • User Property: configfile
  • Default: formatter-maven-plugin/eclipse/java.xml

<configHtmlFile>

File or classpath location of a properties file to use in html formatting.
  • Type: java.lang.String
  • Required: Yes
  • User Property: confightmlfile
  • Default: formatter-maven-plugin/jsoup/html.properties

<configJsFile>

File or classpath location of an Eclipse code formatter configuration xml file to use in formatting.
  • Type: java.lang.String
  • Required: Yes
  • User Property: configjsfile
  • Default: formatter-maven-plugin/eclipse/javascript.xml

<configJsonFile>

File or classpath location of a properties file to use in json formatting.
  • Type: java.lang.String
  • Required: Yes
  • User Property: configjsonfile
  • Default: formatter-maven-plugin/jackson/json.properties

<configXmlFile>

File or classpath location of a properties file to use in xml formatting.
  • Type: java.lang.String
  • Required: Yes
  • User Property: configxmlfile
  • Default: formatter-maven-plugin/eclipse/xml.properties

<directories>

Location of the Java source files to format. Defaults to source main and test directories if not set. Deprecated in version 0.3. Reintroduced in 0.4.
  • Type: java.io.File[]
  • Since: 0.4
  • Required: No

<encoding>

The file encoding used to read and write source files. When not specified and sourceEncoding also not set, default is platform file encoding.
  • Type: java.lang.String
  • Since: 0.3
  • Required: Yes
  • User Property: project.build.sourceEncoding

<excludes>

List of fileset patterns for Java source locations to exclude from formatting. Patterns are relative to the project source and test source directories. When not specified, there is no default exclude.
  • Type: java.lang.String[]
  • Since: 0.3
  • Required: No
  • User Property: formatter.excludes

<includeResources>

When set to true, the resources for the project are included in formatting. This includes both the main and test resources.

The included/excluded patterns for this plugin are honored as well as the included/excluded patterns from the resource itself.

  • Type: boolean
  • Since: 2.22.0
  • Required: No
  • User Property: formatter.includeResources
  • Default: false

<includes>

List of fileset patterns for Java source locations to include in formatting. Patterns are relative to the project source and test source directories. When not specified, the default include is **/*.java
  • Type: java.lang.String[]
  • Since: 0.3
  • Required: No
  • User Property: formatter.includes

<javaExclusionPattern>

A java regular expression pattern that can be used to exclude some portions of the java code from being reformatted.

This can be useful when using DSL that embeds some kind of semantic hierarchy, where users can use various indentation level to increase the readability of the code. Those semantics are ignored by the formatter, so this regex pattern can be used to match certain portions of the code so that they will not be reformatted.

An example is the Apache Camel java DSL which can be used in the following way:

	from("seda:a").routeId("a")
			.log("routing at ${routeId}")
			.multicast()
				.to("seda:b")
				.to("seda:c")
			.end()
			.log("End of routing");

In the above example, the except can be skipped by the formatter by defining the following property in the formatter xml configuration:

  <javaExclusionPattern>\b(from\([^;]*\.end[^;]*?\)\));</javaExclusionPattern>
  • Type: java.lang.String
  • Since: 2.13
  • Required: No
  • User Property: formatter.java.exclusion_pattern

<lineEnding>

Sets the line-ending of files after formatting. Valid values are:
  • "AUTO" - Use line endings of current system
  • "KEEP" - Preserve line endings of files, default to AUTO if ambiguous
  • "LF" - Use Unix and Mac style line endings
  • "CRLF" - Use DOS and Windows style line endings
  • "CR" - Use early Mac style line endings
  • Type: net.revelc.code.formatter.LineEnding
  • Since: 0.2.0
  • Required: Yes
  • User Property: lineending
  • Default: AUTO

<removeTrailingWhitespace>

When set to true, remove trailing whitespace on all lines after the formatter has finished.

Default to 'true' since 2.18.0

  • Type: boolean
  • Since: 2.17.0
  • Required: No
  • User Property: formatter.removeTrailingWhitespace
  • Default: true

<skipCssFormatting>

Whether the css formatting is skipped.
  • Type: boolean
  • Required: No
  • User Property: formatter.css.skip
  • Default: false

<skipFormatting>

Whether the formatting is skipped.
  • Type: boolean
  • Since: 0.5
  • Required: No
  • User Property: formatter.skip
  • Default: false
  • Alias: skip

<skipFormattingCache>

Whether the formatting cache is skipped.
  • Type: boolean
  • Since: 2.23.0
  • Required: No
  • User Property: formatter.cache.skip
  • Default: false

<skipHtmlFormatting>

Whether the html formatting is skipped.
  • Type: boolean
  • Required: No
  • User Property: formatter.html.skip
  • Default: false

<skipJavaFormatting>

Whether the java formatting is skipped.
  • Type: boolean
  • Required: No
  • User Property: formatter.java.skip
  • Default: false

<skipJsFormatting>

Whether the javascript formatting is skipped.
  • Type: boolean
  • Required: No
  • User Property: formatter.js.skip
  • Default: false

<skipJsonFormatting>

Whether the json formatting is skipped.
  • Type: boolean
  • Required: No
  • User Property: formatter.json.skip
  • Default: false

<skipXmlFormatting>

Whether the xml formatting is skipped.
  • Type: boolean
  • Required: No
  • User Property: formatter.xml.skip
  • Default: false

<sourceDirectory>

Project's source directory as specified in the POM.
  • Type: java.io.File
  • Required: Yes
  • User Property: sourceDirectory
  • Default: ${project.build.sourceDirectory}

<testSourceDirectory>

Project's test source directory as specified in the POM.
  • Type: java.io.File
  • Required: Yes
  • User Property: testSourceDirectory
  • Default: ${project.build.testSourceDirectory}

<useEclipseDefaults>

Use eclipse defaults when set to true for java and javascript.
  • Type: boolean
  • Required: No
  • User Property: formatter.useEclipseDefaults
  • Default: false