Spotless for Gradle and Maven

Formats a file on save with the Spotless configuration of its Gradle or Maven build.

It runs your build's own Spotless plugin on the unsaved buffer, so everything the build resolves applies, including build scripts, parent POMs, pluginManagement, profiles, .mvn/maven.config and formatter settings shipped in plugin dependencies.

Gradle

Requirements

• JDK 17 or later.
• Gradle 8.1 or later.
• The Spotless Gradle plugin 8.7.0 or later.
• The Gradle for Java extension 3.12.6 or later.

Usage

To format on save, add this to your settings.

"[java]": {
  "editor.codeActionsOnSave": { "source.fixAll.spotlessForGradleAndMaven": "explicit" },
  "editor.formatOnSave": false
}

Or run Spotless: Format Document from the Command Palette.

Maven

Requirements

• JDK 17 or later.
• Maven 3.6.3 or a later 3.x.
• spotless-maven-plugin 2.40.0 or later. Older versions rewrite the module's files on disk.
• mvnd 1.0.3 or a later 1.x is recommended. It takes about 0.3 s per save, against about 1 s with mvn or mvnw.

Usage

To format on save, add this to your settings.

"[java]": {
  "editor.codeActionsOnSave": { "source.fixAll.spotlessForGradleAndMaven": "explicit" },
  "editor.formatOnSave": false
}

Or run Spotless: Format Document from the Command Palette.

Settings

spotlessForGradleAndMaven.maven.executable sets the Maven executable. When it is empty, the extension uses mvnd on the PATH, then mvnw in the build root, then mvn on the PATH, so a build with mvnw still runs on mvnd if mvnd is installed.

Troubleshooting

If a saved file is not formatted, open the Output panel and select Spotless for Gradle and Maven. A build that fails is logged there with its output. To also log files that no Spotless format targets and the output of every build, run Developer: Set Log Level..., select Spotless for Gradle and Maven, and choose Debug.

Limitations

• With ratchetFrom, the first save after a change is not formatted. With mvnd, later saves may not be formatted either. Set spotlessForGradleAndMaven.maven.executable to mvn in that case.
• A file that more than one Spotless format targets is not formatted, and a warning is logged.
• Steps that use npm, such as prettier, take several seconds.
• In a build without Spotless, every save runs a build that fails, so enable the code action only in workspaces that use Spotless.
• Formatting does not run when files.autoSave is afterDelay, because VS Code runs no code actions on auto save.
• In Maven builds, includes in a parent POM that reach into child module directories, such as **/*.md at the root, are not supported.
• In Maven builds, files in a project that the topmost pom.xml in the workspace does not include as a module, such as a standalone sample project, are not formatted.
• If mvnd keeps using a stale released parent POM, run mvnd --stop.
• On Windows, Maven builds fail when a path contains characters outside the system code page, such as Japanese on an English Windows. This includes the paths of the user profile and the temp folder.
• On Windows, mvnd runs its slower JVM client when a path contains non-ASCII characters, because its native client garbles them.

Privacy

The extension sends no telemetry. To format a file, it writes the unsaved buffer to a new folder under the temp folder, runs your build on it locally, and deletes the folder when the build ends. If VS Code quits before then, the folder is left behind.

Acknowledgements

Inspired by Spotless Gradle by Richard Willis.