You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
feat(spotless/gradle-plugin): Allow SpotlessApply to notify when/what work was done #2715
Hello Spotless team! We're very thankful for your work on this tool. Seeking review on a proposed feature that we are happy to help incorporate into the project if it sounds like a desirable enhancement.
TL;DR:
We'd like to expose information on which files were auto-fixed by SpotlessApply to propagate that information to our developer experience
Problem Statement
Our current team's workflow is as such for running Spotless:
On CI, our invocation of gradle build runs spotlessCheck, as is configured by default. All failures are reported by CI and require manual updates
In local use cases, gradle build will instead run spotlessApply to automatically fix issues. This is biased toward improving the UX during local development
In this case, the developer experience is enhanced by the automatic fixing, however it is less clear when spotlessApply is run on the user's behalf.
It would be preferable to do something more targeted. In this case, we'd prefer to have SpotlessApply (or a finalizer task) only print information in the event that Spotless performed work.
Note
In an ideal world, we'd also be able to show the violations that were fixed during the auto-fix phase, such that we could demonstrate to developers "there were X and Y issues, and we've auto-fixed them". This may be out of scope of this more immediate enhancement, but may be interesting to provide.
(Potential) Design
Enhance the SpotlessApply task to output a simple report containing a manifest of all files it copied in on the most recent execution. This output location can be exposed by the task for the specific gradle build, read, and used to provide a more detailed listing of the edited files.
Note: Theoretical Workaround
We've attempted what we thought would be a suitable workaround for the time being:
// build.gradle.kts (or in convention plugin)
tasks.withType<SpotlessApply>() {
doLast {
if(didWork) {
logger.lifecycle("code auto-formatted by spotlessApply")
}
}
}
Unfortunately, even for cases where there are no changes to any of the source files, the SpotlessApply task is still labeled as didWork == true. If we should file this separately as a "bug", please let us know!
Enhance the SpotlessApply task to output a simple report containing a manifest of all files it copied in on the most recent execution.
We would welcome this contribution.
no changes to any of the source files, the SpotlessApply task is still labeled as didWork == true
No need for a separate bug. Feel free to fix this if you'd like while working on the report feature you want. I'm not sure what's going on, but this might be load-bearing. We definitely have a hint to the check task that if the apply task has already run, then it doesn't need to do anything. Open to revisiting this.
@ffluk3@nedtwigg I opened #3177 for this, following the design proposed here. Feedback very welcome.
What it does
didWork is now accurate. SpotlessApply only reports work when it actually rewrote a file; otherwise it shows UP-TO-DATE. So the original workaround now behaves as intended.
Each apply task writes the files its most recent run changed to build/spotless/<taskName>-changed-files.txt. That's one project-relative path per line, and the file is empty if nothing changed. It is still written when the task then fails on lints. You can change the location with the new changedFilesReport property.
// build.gradle.kts
tasks.withType<SpotlessApply>().configureEach {
val report = changedFilesReport
doLast {
if (didWork) {
logger.lifecycle("Spotless auto-formatted:\n"+ report.get().asFile.readText())
}
}
}
On the "load-bearing" concern:registerApplyAlreadyRan still runs first, so spotlessCheck still skips its work after apply has run. The one visible change: on the build right after a fix, the format task still re-runs (because its input was rewritten), but the apply tasks now show UP-TO-DATE instead of SUCCESS. UpToDateTest asserted the old outcome there, so I updated those three steps.
Open questions:
@ffluk3: does this cover your local build workflow? Is a plain file list enough for now, with "which violations were fixed" left as a possible follow-up?
@nedtwigg: are you happy with the UP-TO-DATE change, and with the default location and property name? Happy to rename or move it.
@ffluk3@nedtwigg I opened #3177 for this, following the design proposed here. Feedback very welcome.
What it does
didWork is now accurate. SpotlessApply only reports work when it actually rewrote a file; otherwise it shows UP-TO-DATE. So the original workaround now behaves as intended.
Each apply task writes the files its most recent run changed to build/spotless/<taskName>-changed-files.txt. That's one project-relative path per line, and the file is empty if nothing changed. It is still written when the task then fails on lints. You can change the location with the new changedFilesReport property.
// build.gradle.kts
tasks.withType().configureEach {
val report = changedFilesReport
doLast {
if (didWork) {
logger.lifecycle("Spotless auto-formatted:\n" + report.get().asFile.readText())
}
}
} On the "load-bearing" concern:registerApplyAlreadyRan still runs first, so spotlessCheck still skips its work after apply has run. The one visible change: on the build right after a fix, the format task still re-runs (because its input was rewritten), but the apply tasks now show UP-TO-DATE instead of SUCCESS. UpToDateTest asserted the old outcome there, so I updated those three steps.
Open questions:
@ffluk3: does this cover your local build workflow? Is a plain file list enough for now, with "which violations were fixed" left as a possible follow-up?
@nedtwigg: are you happy with the UP-TO-DATE change, and with the default location and property name? Happy to rename or move it.
@Pankraz76 at a high level that would give enough as an output to do whatever we'd need to process after the execution. One detail to sort out for your implementation will be how to maintain the ability to participate in task caching with that file as an output, but should be straightforward. Thank you for picking this up! 🙌
changedFilesReport is now a proper @OutputFile (was @Internal). Any task that declares it as an input, e.g. inputs.file(tasks.named('spotlessJavaApply').flatMap { it.changedFilesReport }), gets an implicit dependency on the apply task: no manual dependsOn needed, and that task's up-to-date checks and caching work as expected.
Apply declares outputs but no inputs, so Gradle would otherwise mark it UP-TO-DATE whenever the report is unchanged and skip fixing files. It is now forced to always run via outputs.upToDateWhen { false }, the same approach as the IDE-hook path. Apply itself stays @DisableCachingByDefault, since it rewrites sources in place.
New tests:
a consumer of the report gets the implicit dependency on apply
the consumer works with the configuration cache
apply is never skipped because of an unchanged report (this one fails if upToDateWhen is removed)
@nedtwigg the open questions from my previous comment still stand: is the UP-TO-DATE outcome after a fix OK, and are the default location and property name OK? Happy to adjust.
Activity
nedtwigg commentedon Nov 14, 2025
We would welcome this contribution.
No need for a separate bug. Feel free to fix this if you'd like while working on the report feature you want. I'm not sure what's going on, but this might be load-bearing. We definitely have a hint to the
checktask that if theapplytask has already run, then it doesn't need to do anything. Open to revisiting this.spotless/plugin-gradle/src/main/java/com/diffplug/gradle/spotless/SpotlessApply.java
Lines 32 to 34 in a2ce4e2
spotless/plugin-gradle/src/main/java/com/diffplug/gradle/spotless/SpotlessCheck.java
Lines 65 to 67 in a2ce4e2
Pankraz76 commentedon Nov 8, 2026
@ffluk3 @nedtwigg I opened #3177 for this, following the design proposed here. Feedback very welcome.
What it does
didWorkis now accurate.SpotlessApplyonly reports work when it actually rewrote a file; otherwise it showsUP-TO-DATE. So the original workaround now behaves as intended.build/spotless/<taskName>-changed-files.txt. That's one project-relative path per line, and the file is empty if nothing changed. It is still written when the task then fails on lints. You can change the location with the newchangedFilesReportproperty.On the "load-bearing" concern:
registerApplyAlreadyRanstill runs first, sospotlessCheckstill skips its work after apply has run. The one visible change: on the build right after a fix, the format task still re-runs (because its input was rewritten), but the apply tasks now showUP-TO-DATEinstead ofSUCCESS.UpToDateTestasserted the old outcome there, so I updated those three steps.Open questions:
buildworkflow? Is a plain file list enough for now, with "which violations were fixed" left as a possible follow-up?UP-TO-DATEchange, and with the default location and property name? Happy to rename or move it.Fix BumpThisNumberIfACustomStepChangesTest for accurate apply didWork (…
ffluk3 commentedon Nov 9, 2026
@Pankraz76 at a high level that would give enough as an output to do whatever we'd need to process after the execution. One detail to sort out for your implementation will be how to maintain the ability to participate in task caching with that file as an output, but should be straightforward. Thank you for picking this up! 🙌
SpotlessApply: declare changedFilesReport as an output (diffplug#2715)
Pankraz76 commentedon Nov 9, 2026
Thanks a lot for the feedback @ffluk3, good catch on caching! 🙏
I've pushed an update to #3177:
changedFilesReportis now a proper@OutputFile(was@Internal). Any task that declares it as an input, e.g.inputs.file(tasks.named('spotlessJavaApply').flatMap { it.changedFilesReport }), gets an implicit dependency on the apply task: no manualdependsOnneeded, and that task's up-to-date checks and caching work as expected.UP-TO-DATEwhenever the report is unchanged and skip fixing files. It is now forced to always run viaoutputs.upToDateWhen { false }, the same approach as the IDE-hook path. Apply itself stays@DisableCachingByDefault, since it rewrites sources in place.upToDateWhenis removed)@nedtwigg the open questions from my previous comment still stand: is the
UP-TO-DATEoutcome after a fix OK, and are the default location and property name OK? Happy to adjust.Add failing tests for SpotlessApply changed-files report and didWork (#…
SpotlessApply: report changed files and only set didWork when files c…
SpotlessApply: report changed files and only set didWork when files c…