feat: introduce cli for invoking spotless from shell without any build tool

[simschla]

Motivation

Sometimes, I would love to be able to quickly format some files from my command line, like I'm used to when working on bigger projects, where we've introduced spotless-gradle or spotless-maven. There was no easy way to get the modularity or functionality of spotless without introducing a build for applying the plugin.

So I've asked myself: What if there were a command line interface, a binary that runs superfast and can simply be invoked from the shell without any further setup and even for single files?

This is my proposal to start building such a spotless cli tool - I'm very interested in what @nedtwigg (and of course other contributors and users) think about this approach.

Current State

The current code is still a WIP and has some (very 😉) rough edges that we'd need to smooth out before any of this could be merged, but I think the existing code shows that this could indeed work - and I love it already from using it in my local tests.

The general Idea is to build a cli, that can be used like a "pipeline" (similar to how current spotless-build-plugins are working).

E.g. I'd like to be able to invoke it somehow like this

spotless --generic-params-like-target step-1-eg-like-gjf --params-for-step1 step-2-eg-copyright --params-for-step-2 ...

The current WIP provides the ability to set target-globs for selecting files, allows google-java-format, prettier and copyright/license-header. Adding further formatters is most probably a notable amount of (diligent) work, but I think the current code shows that we can get there.

Example Usage Output

Current API looks like this (showing --help usage output):

1. General Usage:

2. License Header:

3. Google Java Format

4. Prettier

[jbduncan]

Wow, I love the idea! I've been dreaming of something like this on and off over the last few years - I imagine it would be useful for Bazel and make integration - and there's a 5-year-old issue on this very idea: https://github.com/diffplug/spotless/issues/527.

I'll have to find the time to review this in the foreseeable future. Stay tuned.

[jbduncan]

Turns out, I've been dreaming of this for longer than I realised; all the way back since 2017! https://github.com/diffplug/spotless/issues/76

If this becomes a reality, it could be the foundation for a lightweight formatting tool in my non-JVM-based projects. 😁

[nedtwigg]

This looks great! I think you have built something useful that should get published. I'm think it makes sense for diffplug/spotless to point to it as the official CLI. I'm not sure if it should live in this repo or on its own

Reasons to keep it in this repo:

• so that it can interact and sync with the gradle or maven plugins somehow
• so that people making changes to the steps have to deal with accidentally breaking the cli

Reasons to keep it separate

• to make sure it stays isolated from the gradle and maven plugins
• so that people making changes to steps only have 2 downstream projects to worry about instead of 3

I am open to being overruled and putting it into this repo directly, but my preference is for it to live on its own, at least for now. I'm happy to make diffplug/spotless-cli if you want and set it up with the same CI and maven group and all that. Or I'm happy to point to simschla/spotless-cli and you can publish it however you see fit.

[jbduncan]

This looks great! I think you have built something useful that should get published. I'm think it makes sense for diffplug/spotless to point to it as the official CLI. I'm not sure if it should live in this repo or on its own

Reasons to keep it in this repo:

• so that it can interact and sync with the gradle or maven plugins somehow

• so that people making changes to the steps have to deal with accidentally breaking the cli

Reasons to keep it separate

• to make sure it stays isolated from the gradle and maven plugins

• so that people making changes to steps only have 2 downstream projects to worry about instead of 3

I am open to being overruled and putting it into this repo directly, but my preference is for it to live on its own, at least for now. I'm happy to make diffplug/spotless-cli if you want and set it up with the same CI and maven group and all that. Or I'm happy to point to simschla/spotless-cli and you can publish it however you see fit.

I'm not too fussed if it lives here or in a spotless-cli repo either. My preference would be a diffplug repo so it's more official, but I'm happy to leave it to @simschla to decide.

I was about to query if having it in a separate repo was even possible, until I remembered that we publish spotless-lib to Maven Central. 😅

[simschla]

Thank you, @jbduncan and @nedtwigg for the positive feedback, glad to hear you like the idea too 😍

To be honest, I'd also thought about where and how to integrate the cli with current spotless build plugins - a lot of (build and release) stuff is similar, but not quite the same - starting but not limited to the different JVM (Graal for native compilation) and release preparation and distribution (building native for various platforms, maybe delivering via homebrew and friends).

So moving the cli to its own repo makes great sense to me. Even though this might complicate things in the beginning (e.g. when we need to adapt spotless-lib code so it can also be used with the cli).

If you are ok with that, I'd love to host the spotless-cli project under the diffplug umbrella. It is the home of spotless after all and if you are willing to welcome this addition to the family, that would be spectacular! 🎉

Nevertheless: for initial discussions, it might make sense to keep the PR here in draft state open, so we may discuss the poc code easily, if that is OK with you.

[nedtwigg]

Sounds good, happy to keep this open. New repo is open at https://github.com/diffplug/spotless-cli, the same Spotless team that has write access here has write access there.

[jbduncan]

@simschla Sorry for the radio silence! I was planning to review things this weekend, but I see you've just closed the PR, so will you be reopening things on spotless-cli or have you lost interest or something? :)

[simschla]

@jbduncan ah sorry, deleting it was a mistake (too much enthusiasm when housekeeping my fork). I'm working on porting the code over to spotless-cli atm. Will report back as soon as I have something over there 😄