Skip to content

Gradle README: replace -PspotlessFiles with the IDE hook - #3188

Open
0z5a wants to merge 1 commit into
diffplug:mainfrom
0z5a:issue-3183-gradle-specific-files
Open

0z5a wants to merge 1 commit into
diffplug:mainfrom
0z5a:issue-3183-gradle-specific-files

Conversation

@0z5a

@0z5a 0z5a commented Nov 19, 2026

Copy link
Copy Markdown

Fixes #3183

I started from #3183 and checked it against the code. The Gradle README section "Can I apply Spotless to specific files?" (added in #2575, adapted from the Maven README) documents gradle spotlessApply -PspotlessFiles=.... spotlessFiles does not appear anywhere in plugin-gradle/src/main except a javadoc note in FormatExtension.createIndependentApplyTaskLazy; only plugin-maven reads it (AbstractSpotlessMojo). On the Gradle side it was deprecated in 4.3.0 and went away with the other deprecated options in 5.0.0 (#640), per plugin-gradle/CHANGES.md. So the documented command formats the whole target.

This changes the section to say that, and points to what the Gradle plugin does have:

  • -PspotlessIdeHook with a comma-separated list of absolute paths (IdeHook.State splits on ,, and performHook requires absolute paths and skips files outside the target), as described in IDE_HOOK.md;
  • ratchetFrom for formatting only the files changed on a branch.

The section heading and anchor are unchanged, so the table of contents link still works. I added a line under [Unreleased] / Fixed in plugin-gradle/CHANGES.md.

How I found it

I searched plugin-gradle for spotlessFiles and found only the README and the javadoc note, then read plugin-gradle/CHANGES.md for when it was deprecated and removed, and IdeHook.java to check what the replacement accepts.

Where this can show up in practice

Someone who follows the README to format a few files, for example from a pre-commit hook or a script that passes the changed files, gets every file in the target formatted instead, which can touch many unrelated files in one commit. This is my estimate beyond the report in #3183.

Testing

  • Documentation only; I checked the new text against IdeHook.java and IDE_HOOK.md.
  • Not run: a Gradle build with -PspotlessIdeHook, and spotlessCheck on the Markdown files.

The "Can I apply Spotless to specific files?" section documented
-PspotlessFiles, but the Gradle plugin does not read that property: it
was deprecated in 4.3.0 and removed with the other deprecated options in
5.0.0, and only the Maven plugin still has it. Point to
-PspotlessIdeHook, which takes a comma-separated list of absolute paths,
and to ratchetFrom for formatting only changed files.

Fixes diffplug#3183

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Gradle README documents -PspotlessFiles, which the Gradle plugin doesn't read

1 participant