Spotless can check and apply formatting for any plain-text file, with special support for Markdown and Java. It supports several formatters out of the box, including:
- FreshMark (markdown with variables)
- Java style and import ordering (using Eclipse's code formatter)
- License headers
- Tabs vs spaces, trailing whitespace, end with newline, generic regex
- Any user-defined string that takes an unformatted string and outputs a formatted version.
Spotless makes it painless to find and correct formatting errors:
cmd> gradlew build
...
:spotlessJavaCheck FAILED
> Format violations were found. Run 'gradlew spotlessApply' to fix them.
src\test\java\com\diffplug\gradle\spotless\ResourceTest.java
cmd> gradlew spotlessApply
:spotlessApply
BUILD SUCCESSFUL
cmd> gradlew build
BUILD SUCCESSFUL
If you want to audit what spotlessApply will do to your code:
- Save your working tree with
git add -A, thengit commit -m "Checkpoint before spotless.". - Run
gradlew spotlessApply. - View the changes with
git diff. - If you don't like what spotless did,
git reset --hard. - If you'd like to remove the "checkpoint" commit,
git reset --soft head~1will make the checkpoint commit "disappear" from history, but keeps the changes in your working directory.
Contributions are welcome, see the contributing guide for development info.
Can format any version of Java, but requires Gradle to be running on JRE 8+. If you really want to run Gradle on 6 or 7 that could be done, see issue #7 for details.
Spotless is hosted on jcenter and at plugins.gradle.org. Go here if you're not sure how to import the plugin.
- JUnit 5 (aka JUnit Lambda)
- opentest4j
- Durian (direct link to spotless section in its build.gradle)
- DurianRx (direct link to spotless section in it build.gradle)
- DurianSwt (direct link to spotless section in it build.gradle)
- MatConsoleCtl (direct link to spotless section in it build.gradle)
- MatFileRW (direct link to spotless section in it build.gradle)
- Goomph (direct link to spotless section in it build.gradle)
- FreshMark (direct link to spotless section in it build.gradle)
- JScriptBox (direct link to spotless section in it build.gradle)
- (Your project here)
Applying FreshMark to markdown files
To apply freshmark to all of the .md files in your project, with all of your project's properties available for templating, just use this snippet:
spotless {
freshmark {}
}More advanced features are also available:
spotless {
freshmark {
target 'README.md', 'CONTRIBUTING.md'
properties [name: 'Name', version: '1.0.0']
trimTrailingWhitespace()
indentWithTabs() // or spaces. Takes an integer argument if you don't like 4
endWithNewline()
}
}apply plugin: 'java'
...
spotless {
java {
licenseHeader '/* Licensed under Apache-2.0 */' // License header
licenseHeaderFile 'spotless.license.java' // License header file
// Obviously, you can't specify both licenseHeader and licenseHeaderFile at the same time
importOrder ['java', 'javax', 'org', 'com', 'com.diffplug', ''] // An array of package names
importOrderFile 'spotless.importorder' // An import ordering file, exported from Eclipse
// As before, you can't specify both importOrder and importOrderFile at the same time
// You probably want an empty string at the end - all of the imports you didn't specify
// explicitly will go there.
eclipseFormatFile 'spotless.eclipseformat.xml' // XML file dumped out by the Eclipse formatter
// If you have an older Eclipse properties file, you can use that too.
// You can also tweak the formatting with custom regexes or functions, such as:
// Eclipse formatter screws up long literals with underscores inside of annotations (see issue #14)
// @Max(value = 9_999_999 L) // what Eclipse does
// @Max(value = 9_999_999L) // what I wish Eclipse did
custom 'Long literal fix', { it.replaceAll('([0-9_]+) [Ll]', '$1L') }
// By default, all Java source sets will be formatted. To change
// this, set the 'target' parameter as described in the next section.
}
}Spotless has a generic system for specifying which transformations to apply to which files. This makes it easy to apply simple formatting rules (indentation, trailing whitespace, etc) to all of your source plaintext.
spotless {
// this will create two tasks: spotlessMiscCheck and spotlessMiscApply
format 'misc', {
// target determines which files this format will apply to
// - if you pass a string or a list of strings, they will be treated
// as 'include' parameters to a fileTree in the root directory
// - if you pass a FileCollection, it will pass through untouched
// e.g. project.files('build.gradle', 'settings.gradle')
// - if you pass anything else, it will be sent to project.files(yourArg)
target '**/*.gradle', '**/*.md', '**/.gitignore'
// spotless has built-in rules for the most basic formatting tasks
trimTrailingWhitespace()
indentWithTabs() // or spaces. Takes an integer argument if you don't like 4
endWithNewline()
}
format 'cpp', {
target '**/*.hpp', '**/*.cpp'
// you can add simple replace rules
customReplace 'Not enough space after if', 'if(', 'if ('
// or complex regex rules
customReplaceRegex 'Too much space after if', 'if +\\(', 'if ('
// Everything before the first #include or #pragma will be replaced with the header
licenseHeaderFile 'spotless.license.cpp', '#'
// The '#' is treated as regex which is applied to each line, so you can
// make a more complex header delimiter if you require it
// you can also call out to your own function
custom 'superFormatter', {
// when writing a custom step, it will be helpful to know
// how the formatting process works, which is as follows:
// 1) Load each target file, and convert it to unix-style line endings ('\n')
// 2) Pass its content through a series of steps, feeding the output of each step to the next
// 3) Put the correct line endings back on, then either check or apply
// each step receives a string as input, and should output
// a formatted string as output. Each step can trust that its
// input will have unix newlines, and it must promise to output
// only unix newlines. Other than that, anything is fair game!
}
}
// If you'd like to specify that files should always have a certain line ending, you can,
// but the default value of PLATFORM_NATIVE is *highly* recommended
lineEndings = PLATFORM_NATIVE // can be WINDOWS, UNIX, or PLATFORM_NATIVE
}See FormatExtension.java for further details on the default rules.
See JavaExtension.java for further details on how the Java formatter is implemented.
- Formatting by Eclipse 4.5
- Special thanks to Mateusz Matela for huge improvements to the eclipse code formatter!
- Forked from gradle-format-plugin by Youri Bonnaff??.
- Thanks to G??bor Bern??t for improvements to logging and multi-project support.
- Import ordering from EclipseCodeFormatter.
- Built by gradle.
- Tested by junit.
- Maintained by DiffPlug.
There are two files to import / export with Eclipse - one for code formatting and one for import ordering.
Eclipse formatter's off / on tags are a great feature which is often overlooked.
