Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions gradle/pinned-libs.versions.toml
Original file line number Diff line number Diff line change
Expand Up @@ -15,3 +15,9 @@ google-java-format = "com.google.googlejavaformat:google-java-format:1.28.0"
diktat-rules = "org.cqfn.diktat:diktat-rules:1.2.5"
aether-api = "org.eclipse.aether:aether-api:1.1.0"
plexus-build-api = "org.sonatype.plexus:plexus-build-api:0.0.7"
# API floor for the spotless:report goal. maven-site-plugin supplies its own copy at runtime, and the report
# only calls methods that Doxia 1 (maven-site-plugin 3.12.x) has too, so don't raise these casually.
maven-reporting-api = "org.apache.maven.reporting:maven-reporting-api:4.0.0"
doxia-sink-api = "org.apache.maven.doxia:doxia-sink-api:2.0.0"
# Xpp3Dom, which Maven 3 supplies at runtime; plexus-utils 4 moved it out into plexus-xml.
plexus-xml = "org.codehaus.plexus:plexus-xml:3.0.1"
3 changes: 3 additions & 0 deletions plugin-maven/CHANGES.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,9 @@
We adhere to the [keepachangelog](https://keepachangelog.com/en/1.0.0/) format (starting after version `1.27.0`).

## [Unreleased]
### Added
- Add a `spotless:report` goal that puts a Spotless page in the Maven site. ([#3175](https://github.com/diffplug/spotless/pull/3175))
List `spotless-maven-plugin` under `<reporting>` and run `mvn site`: the page shows which files need formatting, with a colored diff for each, and their lint problems. It works with `maven-site-plugin` 3.12.1 and 3.20.0 or later.
### Fixed
- GrEclipse no longer leaves a `file%3A...` directory in the working directory. ([#2019](https://github.com/diffplug/spotless/issues/2019))

Expand Down
37 changes: 35 additions & 2 deletions plugin-maven/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -72,6 +72,7 @@ user@machine repo % mvn spotless:check
- [Line endings and encodings (invisible stuff)](#line-endings-and-encodings-invisible-stuff)
- [Disabling warnings and error messages](#disabling-warnings-and-error-messages)
- [How do I preview what `mvn spotless:apply` will do?](#how-do-i-preview-what-mvn-spotlessapply-will-do)
- [Maven site report](#maven-site-report)
- [Can I apply Spotless to specific files?](#can-i-apply-spotless-to-specific-files)
- [How to centralize Spotless configuration](#central-configuration)
- [Example configurations (from real-world projects)](#example-configurations-from-real-world-projects)
Expand Down Expand Up @@ -2173,15 +2174,17 @@ By default, `spotless:check` is bound to the `verify` phase. You might want to d

| Property | Scope | Effect |
| --- | --- | --- |
| `spotless.skip` | `spotless:check` and `spotless:apply` | Skips both formatting goals |
| `spotless.skip` | `spotless:check`, `spotless:apply` and `spotless:report` | Skips all three goals |
| `spotless.check.skip` | `spotless:check` only | Skips only the check goal |
| `spotless.apply.skip` | `spotless:apply` only | Skips only the apply goal |
| `spotless.report.skip` | `spotless:report` only | Skips only the [site report](#maven-site-report) |

You can set them at the command line or in the `<properties>` section of the `pom.xml`:

- `-Dspotless.skip=true` / `<spotless.skip>true</spotless.skip>` — skip both `spotless:check` and `spotless:apply`
- `-Dspotless.skip=true` / `<spotless.skip>true</spotless.skip>` — skip `spotless:check`, `spotless:apply` and `spotless:report`
- `-Dspotless.check.skip=true` / `<spotless.check.skip>true</spotless.check.skip>` — skip only `spotless:check` (including when it is bound to `verify`)
- `-Dspotless.apply.skip=true` / `<spotless.apply.skip>true</spotless.apply.skip>` — skip only `spotless:apply`
- `-Dspotless.report.skip=true` / `<spotless.report.skip>true</spotless.report.skip>` — skip only `spotless:report`

`spotless.check.skip` does **not** skip `spotless:apply`, and `spotless.apply.skip` does **not** skip `spotless:check`. Use `spotless.skip` when you want both. These properties do **not** affect `spotless:install-git-pre-push-hook`.

Expand Down Expand Up @@ -2253,6 +2256,36 @@ Spotless is primarily a formatter, _not_ a linter. In our opinion, a linter is j
- If you don't like what spotless did, `git reset --hard`
- If you'd like to remove the "checkpoint" commit, `git reset --soft head~1` will make the checkpoint commit "disappear" from history, but keeps the changes in your working directory.

You can also look at the changes without applying them, in the [site report](#maven-site-report).

## Maven site report

`spotless:report` adds a **Spotless** page to the site that `mvn site` builds. List the plugin in the `<reporting>` section of your `pom.xml`:

```xml
<reporting>
<plugins>
<plugin>
<groupId>com.diffplug.spotless</groupId>
<artifactId>spotless-maven-plugin</artifactId>
<version>${spotless.version}</version>
</plugin>
</plugins>
</reporting>
```

You don't need to repeat your Spotless configuration: the report uses the plugin-level `<configuration>` of the Spotless plugin in your `<build>` section, except for anything you set in `<reporting>` itself. Configuration inside an `<execution>` is not used.

`mvn site` then lists Spotless under *Project Reports*. The page shows, for each format, how many files are clean, need formatting or have lint problems. Each file with a problem gets its own page, with a colored diff of the changes `mvn spotless:apply` would make and a table of its lint problems.

The report checks the same files as `spotless:check`, so `ratchetFrom`, `spotlessFiles` and `<lintSuppressions>` apply to it. It never changes your files, never fails the build because of violations, and ignores the [up-to-date index](#incremental-up-to-date-checking-and-formatting), so every file is checked.

- `mvn spotless:report` writes the report to `target/site/spotless.html` without building the whole site. Run this way, it reads only the configuration in `<build>`, because Maven never applies `<reporting>` to goals you run directly. If you use both, put report options such as `<maxDiffLines>` in `<build>`.
- `<maxDiffLines>` (default `1000`, `0` for no limit) limits how many lines of diff each file's page shows. `-Dspotless.report.maxDiffLines` sets it from the command line.
- `-Dspotless.report.skip=true` skips the report, and so does `-Dspotless.skip=true`.

The report works with `maven-site-plugin` 3.12.1, which Maven 3.9 uses by default, and with 3.20.0 or later.

## Can I apply Spotless to specific files?

You can target specific files by setting the `spotlessFiles` project property to a comma-separated list of file patterns:
Expand Down
4 changes: 4 additions & 0 deletions plugin-maven/build.gradle.kts
Original file line number Diff line number Diff line change
Expand Up @@ -40,6 +40,7 @@ dependencies {
compileOnly(pinnedLibs.maven.plugin.annotations)
compileOnly(pinnedLibs.maven.core)
compileOnly(pinnedLibs.aether.api)
compileOnly(pinnedLibs.plexus.xml)

compileOnly(libs.jakarta.annotation.api)
compileOnly(libs.javax.inject)
Expand All @@ -51,6 +52,9 @@ dependencies {
implementation(libs.plexus.utils)
implementation(libs.jgit)
implementation(pinnedLibs.plexus.build.api)
// spotless:report; only these two small API jars, no Doxia renderer
implementation(pinnedLibs.maven.reporting.api)
implementation(pinnedLibs.doxia.sink.api)

testImplementation(projects.testlib)
testImplementation(libs.junit.jupiter)
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -102,6 +102,7 @@ public abstract class AbstractSpotlessMojo extends AbstractMojo {
static final String GOAL_CHECK = "check";
static final String GOAL_APPLY = "apply";
static final String GOAL_PRE_PUSH_HOOK = "install-git-pre-push-hook";
static final String GOAL_REPORT = "report";

@Inject
private RepositorySystem repositorySystem;
Expand Down Expand Up @@ -290,9 +291,26 @@ public final void execute() throws MojoExecutionException {
} catch (PluginException e) {
throw e.asMojoExecutionException();
}
afterProcessing();
}

private boolean shouldSkip() {
/**
* Called once after every format has been processed and the formatters have been closed.
* Goals that collect results in {@link #process}, such as {@code spotless:report}, act on them here.
*/
protected void afterProcessing() throws MojoExecutionException {}

/**
* Whether this goal uses the up-to-date index, which skips files that were clean the last time
* {@code spotless:check} or {@code spotless:apply} ran. Goals that must look at every file without
* touching that index, such as {@code spotless:report}, return {@code false}.
*/
protected boolean usesUpToDateIndex() {
return true;
}

/** Returns {@code true} if this goal should do nothing, because of {@code spotless.skip}, a goal-specific skip flag, or an m2e incremental build. */
protected final boolean shouldSkip() {
if (skip) {
return true;
}
Expand Down Expand Up @@ -463,6 +481,9 @@ private List<FormatterStepFactory> getFormatterStepFactories() {
}

private UpToDateChecker createUpToDateChecker(Iterable<Formatter> formatters) {
if (!usesUpToDateIndex()) {
return UpToDateChecker.ignoringIndex();
}
Path indexFile = upToDateChecking == null ? null : upToDateChecking.getIndexFile();
if (indexFile == null) {
Path targetDir = project.getBasedir().toPath().resolve(project.getBuild().getDirectory());
Expand Down
Loading
Loading