Docs about up-to-date checking for Maven plugin

README.md

@@ -42,7 +42,7 @@ output = [
 '| Toggle with [`spotless:off` and `spotless:on`](plugin-gradle/#spotlessoff-and-spotlesson) | {{yes}}    | {{yes}}      | {{no}}       | {{no}}  |',
 '| [Ratchet from](https://github.com/diffplug/spotless/tree/main/plugin-gradle#ratchet) `origin/main` or other git ref | {{yes}}    | {{yes}}      | {{no}}       | {{no}}  |',
 '| Define [line endings using git](https://github.com/diffplug/spotless/tree/main/plugin-gradle#line-endings-and-encodings-invisible-stuff) | {{yes}}    | {{yes}}      | {{yes}}       | {{no}}  |',
-'| Fast incremental format and up-to-date check   | {{yes}}      | {{no}}       | {{no}}       | {{no}}  |',
+'| Fast incremental format and up-to-date check   | {{yes}}      | {{yes}}      | {{no}}       | {{no}}  |',
 '| Fast format on fresh checkout using buildcache | {{yes}}      | {{no}}       | {{no}}       | {{no}}  |',
 lib('generic.EndWithNewlineStep')                +'{{yes}}       | {{yes}}      | {{no}}       | {{no}}  |',
 lib('generic.IndentStep')                        +'{{yes}}       | {{yes}}      | {{no}}       | {{no}}  |',
@@ -81,7 +81,7 @@ extra('wtp.EclipseWtpFormatterStep')             +'{{yes}}       | {{yes}}
 | Toggle with [`spotless:off` and `spotless:on`](plugin-gradle/#spotlessoff-and-spotlesson) | :+1:    | :+1:      | :white_large_square:       | :white_large_square:  |
 | [Ratchet from](https://github.com/diffplug/spotless/tree/main/plugin-gradle#ratchet) `origin/main` or other git ref | :+1:    | :+1:      | :white_large_square:       | :white_large_square:  |
 | Define [line endings using git](https://github.com/diffplug/spotless/tree/main/plugin-gradle#line-endings-and-encodings-invisible-stuff) | :+1:    | :+1:      | :+1:       | :white_large_square:  |
-| Fast incremental format and up-to-date check   | :+1:      | :white_large_square:       | :white_large_square:       | :white_large_square:  |
+| Fast incremental format and up-to-date check   | :+1:      | :+1:      | :white_large_square:       | :white_large_square:  |
 | Fast format on fresh checkout using buildcache | :+1:      | :white_large_square:       | :white_large_square:       | :white_large_square:  |
 | [`generic.EndWithNewlineStep`](lib/src/main/java/com/diffplug/spotless/generic/EndWithNewlineStep.java) | :+1:       | :+1:      | :white_large_square:       | :white_large_square:  |
 | [`generic.IndentStep`](lib/src/main/java/com/diffplug/spotless/generic/IndentStep.java) | :+1:       | :+1:      | :white_large_square:       | :white_large_square:  |

plugin-maven/README.md

@@ -900,6 +900,47 @@ If your project has not been rigorous with copyright headers, and you'd like to
 
 <a name="ratchet"></a>
 
+## Incremental up-to-date checking and formatting
+
+**This feature is turned off by default.**
+
+Execution of `spotless:check` and `spotless:apply` for large projects can take time.
+By default, Spotless Maven plugin needs to read and format each source file.
+Repeated executions of `spotless:check` or `spotless:apply` are completely independent.
+
+If your project has many source files managed by Spotless and formatting takes a long time, you can
+enable incremental up-to-date checking with the following configuration:
+
+```xml
+<configuration>
+  <upToDateChecking>
+    <enabled>true</enabled>
+  </upToDateChecking>
+  <!-- ... define formats ... -->
+</configuration>
+```
+
+With up-to-date checking enabled, Spotless creates an index file in the `target` directory.
+The index file contains source file paths and corresponding last modified timestamps.
+It allows Spotless to skip already formatted files that have not changed.
+
+**Note:** the index file is located in the `target` directory. Executing `mvn clean` will delete
+the index file, and Spotless will need to check/format all the source files.
+
+Spotless will remove the index file when up-to-date checking is explicitly turned off with the
+following configuration:
+
+```xml
+<configuration>
+  <upToDateChecking>
+    <enabled>false</enabled>
+  </upToDateChecking>
+  <!-- ... define formats ... -->
+</configuration>
+```
+
+Consider using this configuration if you experience issues with up-to-date checking.
+
 ## How can I enforce formatting gradually? (aka "ratchet")
 
 If your project is not currently enforcing formatting, then it can be a noisy transition.  Having a giant commit where every single file gets changed makes the history harder to read.  To address this, you can use the `ratchet` feature: