Document and localize Maven skip properties (#3009)

Author: nedtwigg

plugin-maven/CHANGES.md

@@ -6,6 +6,7 @@ We adhere to the [keepachangelog](https://keepachangelog.com/en/1.0.0/) format (
 ### Fixed
 - Concurrent P2 provisioning no longer races Solstice's on-disk cache (affects Eclipse-based formatters under parallel builds). ([#3004](https://github.com/diffplug/spotless/issues/3004))
 ### Changes
+- Document Maven skip properties `spotless.skip`, `spotless.check.skip`, and `spotless.apply.skip`. Goal-specific skips now live on their own mojos so they no longer leak across goals. ([#3009](https://github.com/diffplug/spotless/pull/3009))
 - Bump default `adocfmt` version `0.2.0` -> `0.3.1`, which adds table formatting support (`<formatTables>`, `<tableLayout>`, `<tableMaxLineWidth>`, `<tableBlankLines>`).
 - Add support to apply alternate license header within same format ([#872](https://github.com/diffplug/spotless/issues/872))
 - Add support to skip license header application based on source file content pattern ([#650](https://github.com/diffplug/spotless/issues/650)).

plugin-maven/README.md

@@ -2104,12 +2104,23 @@ You can easily set the line endings of different files using [a `.gitattributes`
 
 <a name="enforceCheck"></a>
 
-## Disabling warnings and error messages
+## Disabling Spotless goals
 
-By default, `spotless:check` is bound to the `verify` phase.  You might want to disable this behavior.  We [recommend against this](https://github.com/diffplug/spotless/issues/79#issuecomment-290844602), but it's easy to do if you'd like:
+By default, `spotless:check` is bound to the `verify` phase. You might want to disable Spotless for some builds. We [recommend against this](https://github.com/diffplug/spotless/issues/79#issuecomment-290844602), but the following properties are available:
 
-- set `-Dspotless.check.skip=true` at the command line
-- set `spotless.check.skip` to `true` in the `<properties>` section of the `pom.xml`
+| Property | Scope | Effect |
+| --- | --- | --- |
+| `spotless.skip` | `spotless:check` and `spotless:apply` | Skips both formatting goals |
+| `spotless.check.skip` | `spotless:check` only | Skips only the check goal |
+| `spotless.apply.skip` | `spotless:apply` only | Skips only the apply goal |
+
+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.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`
+
+`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`.
 
 ### Suppressing lint errors
 

plugin-maven/src/main/java/com/diffplug/spotless/maven/AbstractSpotlessMojo.java

@@ -120,12 +120,6 @@ public abstract class AbstractSpotlessMojo extends AbstractMojo {
 	@Parameter(property = "spotless.skip", defaultValue = "false")
 	private boolean skip;
 
-	@Parameter(property = "spotless.apply.skip", defaultValue = "false")
-	private boolean applySkip;
-
-	@Parameter(property = "spotless.check.skip", defaultValue = "false")
-	private boolean checkSkip;
-
 	@Parameter(defaultValue = "${project}", required = true, readonly = true)
 	private MavenProject project;
 
@@ -305,16 +299,14 @@ private boolean shouldSkip() {
 			getLog().debug("Skipping for incremental builds as parameter 'enableForIncrementalBuilds' is set to 'false'");
 			return true;
 		}
+		return isGoalSpecificSkip();
+	}
 
-		switch (goal) {
-		case GOAL_CHECK:
-			return checkSkip;
-		case GOAL_APPLY:
-			return applySkip;
-		default:
-			break;
-		}
-
+	/**
+	 * Goal-specific skip flags live on the concrete mojos (e.g. {@code spotless.check.skip}).
+	 * Override when a goal has its own property.
+	 */
+	protected boolean isGoalSpecificSkip() {
 		return false;
 	}
 

plugin-maven/src/main/java/com/diffplug/spotless/maven/SpotlessApplyMojo.java

@@ -47,6 +47,14 @@ public class SpotlessApplyMojo extends AbstractSpotlessMojo {
 	@Parameter(property = "spotlessIdeHookUseStdOut")
 	private boolean spotlessIdeHookUseStdOut;
 
+	@Parameter(property = "spotless.apply.skip", defaultValue = "false")
+	private boolean applySkip;
+
+	@Override
+	protected boolean isGoalSpecificSkip() {
+		return applySkip;
+	}
+
 	@Override
 	protected void process(String name, Iterable<File> files, Formatter formatter, UpToDateChecker upToDateChecker) throws MojoExecutionException {
 		if (isIdeHook()) {

plugin-maven/src/main/java/com/diffplug/spotless/maven/SpotlessCheckMojo.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2016-2025 DiffPlug
+ * Copyright 2016-2026 DiffPlug
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -41,6 +41,9 @@ public class SpotlessCheckMojo extends AbstractSpotlessMojo {
 
 	private static final String INCREMENTAL_MESSAGE_PREFIX = "Spotless Violation: ";
 
+	@Parameter(property = "spotless.check.skip", defaultValue = "false")
+	private boolean checkSkip;
+
 	public enum MessageSeverity {
 		WARNING(BuildContext.SEVERITY_WARNING), ERROR(BuildContext.SEVERITY_ERROR);
 
@@ -63,6 +66,11 @@ public int getSeverity() {
 	@Parameter(defaultValue = "WARNING")
 	private MessageSeverity m2eIncrementalBuildMessageSeverity;
 
+	@Override
+	protected boolean isGoalSpecificSkip() {
+		return checkSkip;
+	}
+
 	@Override
 	protected void process(String name, Iterable<File> files, Formatter formatter, UpToDateChecker upToDateChecker) throws MojoExecutionException {
 		ImpactedFilesTracker counter = new ImpactedFilesTracker();

plugin-maven/src/test/java/com/diffplug/spotless/maven/SpotlessCheckMojoTest.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2016-2023 DiffPlug
+ * Copyright 2016-2026 DiffPlug
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -27,6 +27,7 @@ class SpotlessCheckMojoTest extends MavenIntegrationHarness {
 
 	private static final String UNFORMATTED_FILE = "license/MissingLicense.test";
 	private static final String FORMATTED_FILE = "license/HasLicense.test";
+	private static final String TARGET_JAVA = "src/main/java/com.github.youribonnaffe.gradle.format/Java8Test.java";
 
 	@Test
 	void testSpotlessCheckWithFormattingViolations() throws Exception {
@@ -46,6 +47,19 @@ void testSkipSpotlessCheckWithFormattingViolations() throws Exception {
 		testSpotlessCheck(UNFORMATTED_FILE, "spotless:check -Dspotless.check.skip", false);
 	}
 
+	@Test
+	void testSkipAllGoalsWithSpotlessSkip() throws Exception {
+		writePomWithJavaLicenseHeaderStep();
+		testSpotlessCheck(UNFORMATTED_FILE, "spotless:check -Dspotless.skip", false);
+	}
+
+	@Test
+	void testApplySkipDoesNotSkipCheck() throws Exception {
+		writePomWithJavaLicenseHeaderStep();
+		// apply.skip must not suppress check
+		testSpotlessCheck(UNFORMATTED_FILE, "spotless:check -Dspotless.apply.skip", true);
+	}
+
 	@Test
 	void testSpotlessCheckBindingToVerifyPhase() throws Exception {
 		writePom(
@@ -68,9 +82,39 @@ void testSpotlessCheckBindingToVerifyPhase() throws Exception {
 		testSpotlessCheck(UNFORMATTED_FILE, "verify", true);
 	}
 
+	@Test
+	void testApplySkipLeavesFileUnformatted() throws Exception {
+		writePomWithJavaLicenseHeaderStep();
+		setFile("license.txt").toResource("license/TestLicense");
+		setFile(TARGET_JAVA).toResource(UNFORMATTED_FILE);
+
+		mavenRunner().withArguments("spotless:apply -Dspotless.apply.skip").runNoError();
+		assertFile(TARGET_JAVA).sameAsResource(UNFORMATTED_FILE);
+	}
+
+	@Test
+	void testSpotlessSkipLeavesApplyUnformatted() throws Exception {
+		writePomWithJavaLicenseHeaderStep();
+		setFile("license.txt").toResource("license/TestLicense");
+		setFile(TARGET_JAVA).toResource(UNFORMATTED_FILE);
+
+		mavenRunner().withArguments("spotless:apply -Dspotless.skip").runNoError();
+		assertFile(TARGET_JAVA).sameAsResource(UNFORMATTED_FILE);
+	}
+
+	@Test
+	void testCheckSkipDoesNotSkipApply() throws Exception {
+		writePomWithJavaLicenseHeaderStep();
+		setFile("license.txt").toResource("license/TestLicense");
+		setFile(TARGET_JAVA).toResource(UNFORMATTED_FILE);
+
+		mavenRunner().withArguments("spotless:apply -Dspotless.check.skip").runNoError();
+		assertFile(TARGET_JAVA).sameAsResource(FORMATTED_FILE);
+	}
+
 	private void testSpotlessCheck(String fileName, String command, boolean expectError) throws Exception {
 		setFile("license.txt").toResource("license/TestLicense");
-		setFile("src/main/java/com.github.youribonnaffe.gradle.format/Java8Test.java").toResource(fileName);
+		setFile(TARGET_JAVA).toResource(fileName);
 
 		MavenRunner mavenRunner = mavenRunner().withArguments(command);