From 7b8c3e019b4d1673c01513ace9bf1fbe6fe12eb6 Mon Sep 17 00:00:00 2001
From: Nick Cross <ncross@redhat.com>
Date: Thu, 25 Sep 2025 09:30:09 +0100
Subject: [PATCH] Add documentation showing how to share configuration

---
 plugin-gradle/README.md | 21 +++++++++++++++++++++
 plugin-maven/README.md  | 33 +++++++++++++++++++++++++++++++++
 2 files changed, 54 insertions(+)

diff --git a/plugin-gradle/README.md b/plugin-gradle/README.md
index ac7b0f4ede..32093d1980 100644
--- a/plugin-gradle/README.md
+++ b/plugin-gradle/README.md
@@ -93,6 +93,7 @@ Spotless supports all of Gradle's built-in performance features (incremental bui
   - [Dependency resolution modes](#dependency-resolution-modes)
   - [How do I preview what `spotlessApply` will do?](#how-do-i-preview-what-spotlessapply-will-do)
   - [Can I apply Spotless to specific files?](#can-i-apply-spotless-to-specific-files)
+  - [Sharing Spotless Configuration](#sharing-configuration)
   - [Example configurations (from real-world projects)](#example-configurations-from-real-world-projects)
 
 ***Contributions are welcome, see [the contributing guide](../CONTRIBUTING.md) for development info.***
@@ -1908,6 +1909,26 @@ cmd> gradle spotlessApply -PspotlessFiles=my/file/pattern.java,more/generic/.*-p
 
 The patterns are matched using `String#matches(String)` against the absolute file path.
 
+## Sharing Configuration
+
+Rather than copying the formatter files across many projects, it is possible to define a common configuration that is deployed as a standard artifact so that it can be then be reused by each project; for example:
+
+```kotlin
+    val spotlessConfig by configurations.creating
+    dependencies {
+        spotlessConfig("org.mycompany:code-configuration:1.0.0")
+    }
+    spotless {
+        java {
+            removeUnusedImports()
+            importOrder(resources.text.fromArchiveEntry(spotlessConfig, "java-import-order.txt").asString())
+            eclipse().configXml(resources.text.fromArchiveEntry(spotlessConfig, "java-formatter.xml").asString())
+        }
+    }
+```
+
+In this example, the files `java-import-order.txt` and `java-formatter.xml` should be at the root of the deployed `org.mycompany:code-configuration:1.0.0` jar.
+
 ## Example configurations (from real-world projects)
 
 * [A few thousand github projects](https://github.com/search?l=gradle&q=spotless&type=Code)
diff --git a/plugin-maven/README.md b/plugin-maven/README.md
index 7de87eb5fa..447026af0a 100644
--- a/plugin-maven/README.md
+++ b/plugin-maven/README.md
@@ -72,6 +72,7 @@ user@machine repo % mvn spotless:check
   - [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)
   - [Can I apply Spotless to specific files?](#can-i-apply-spotless-to-specific-files)
+  - [Sharing Spotless Configuration](#sharing-configuration)
   - [Example configurations (from real-world projects)](#example-configurations-from-real-world-projects)
 
 ***Contributions are welcome, see [the contributing guide](../CONTRIBUTING.md) for development info.***
@@ -2052,6 +2053,38 @@ Note that for Incremental build support the goals have to be bound to a phase pr
 
 <a name="examples"></a>
 
+## Sharing Configuration
+
+Rather than copying the formatter files across many projects, it is possible to define a common configuration that is deployed as a standard artifact so that it can be then be reused by each project; for example:
+
+```
+<plugin>
+  <groupId>com.diffplug.spotless</groupId>
+  <artifactId>spotless-maven-plugin</artifactId>
+  <version>${spotless-maven-plugin.version}</version>
+  <dependencies>
+    <dependency>
+      <groupId>org.mycompany</groupId>
+      <artifactId>code-configuration</artifactId>
+      <version>1.0.0</version>
+    </dependency>
+  </dependencies>
+  <configuration>
+    <java>
+      <removeUnusedImports/>
+      <importOrder>
+        <file>java-import-order.txt</file>
+      </importOrder>
+      <eclipse>
+        <file>java-formatter.xml</file>
+      </eclipse>
+      <lineEndings>UNIX</lineEndings>
+    </java>
+  </configuration>
+```
+
+In this example, the files `java-import-order.txt` and `java-formatter.xml` should be at the root of the deployed `org.mycompany:code-configuration:1.0.0` jar.
+
 ## Example configurations (from real-world projects)
 
 - [Apache Avro](https://github.com/apache/avro/blob/8026c8ffe4ef67ab419dba73910636bf2c1a691c/lang/java/pom.xml#L307-L334)