Skip to content

feat(spotless/gradle-plugin): Allow SpotlessApply to notify when/what work was done #2715

Closed

Description

@ffluk3

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!

Activity

  1. nedtwigg commented on Nov 14, 2025

    @nedtwigg
    Member

    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.

  2. Pankraz76 commented on Nov 8, 2026

    @Pankraz76

    @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:

    1. @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?
    2. @nedtwigg: are you happy with the UP-TO-DATE change, and with the default location and property name? Happy to rename or move it.
  3. ffluk3 commented on Nov 9, 2026

    @ffluk3
    Author

    @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:

    1. @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?
    2. @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! 🙌

  4. Pankraz76 commented on Nov 9, 2026

    @Pankraz76

    Thanks a lot for the feedback @ffluk3, good catch on caching! 🙏

    I've pushed an update to #3177:

    • 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.

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

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions