prettier --lint / --check mode

Prettier CLI has an interesting option called --list-different, which is designed to fail the CI if not all files are formatted. That’s a nice perk for those who want to stick with good practices, so it’s great that Prettier has such an execution mode built into the core!

In my opinion, one minor problem with --list-different as means to check the code base is that it’s not quite ‘humane’. The output is just a list of unformatted files, which is fine for piping them to another command but probably a bit too ‘dry’ for a human to interpret. A repo contributor who’s CI pipeline has failed will see something like:

$ yarn install
...
✨  Done in 23.41s.

$ yarn prettier --list-different "src/**/*.js"
src/fileA.js
src/fileB.js
error Command failed with exit code 1.
info Visit https://yarnpkg.com/en/docs/cli/run for documentation about this command.

It’s a bit hard to say what’s behind the failure and what to do with this, isn’t it? To solve a probable confusion, there exist two npm modules that I know of: prettier-check by @hexacta and prettylint by @ikatyang. Frankly speaking, their sole goal is to provide alternatives to --list-different that would simply output some text for humans in addition to the very same file list. Here’s what I see in CI when utilizing prettier-check instead of prettier --list-different:

$ yarn prettier-check "src/**/*.js"
Forgot to run prettier? There are files without correct code style:
src/fileA.js
src/fileB.js

error Command failed with exit code 3.
info Visit https://yarnpkg.com/en/docs/cli/run for documentation about this command.

or if I’m lucky:

yarn prettier-check "src/**/*.js"
All files using prettier code style.
✨  Done in 1.89s.

The output is much better as it makes perfect sense!

Given that the distinction between --list-different and an external npm module is purely cosmetic, would not it be great to install just one npm dependency instead of two? This would not only ease the project setup process, but also make the dependency tree much lighter:

cd new-project-with-prettier
yarn init --yes
yarn add --dev prettier
## node_modules: 8.5MB, 8 lines in yarn.lock listing 1 package

cd new-project-with-prettier-check
yarn init --yes
yarn add --dev prettier prettier-check
## node_modules: 8.9MB, 116 lines in yarn.lock listing 18 packages

cd new-project-with-prettylint
yarn init --yes
yarn add --dev prettier prettylint
## node_modules: 10MB, 550 lines in yarn.lock listing 85 packages

(I used du -sh node_modules to get the size of node_modules, wc -l yarn.lock to count the number of lines in yarn.lock and tr -cd '@' < yarn.lock | wc -c to extract the number of packages)

It’d be quite helpful if Prettier had a flavour of --list-different that could be as informative as prettier-check and prettylint, but come at a cost of just a few lines of code in the core instead of tens of additional modules with all their maintainability and security concerns. Can we say that running Prettier as a ‘humane’ linter in CI is common enough that we can make this execution mode a part of the core? My experience and intuition suggest that the answer is yes.

A humane version of --list-different option could even print a command that would work as cure to a failure – this has been suggested in https://github.com/prettier/prettier/issues/5277. One more prior discussion I could dig out is in https://github.com/prettier/prettier/issues/4911.

If there are no blockers such as factors I haven’t considered, I’m happy to submit a small PR. It would implement a new flavour of --list-different (say, an option called --lint or --check) and thus make it easier for everyone to run Prettier in CI. Hope this saves time, effort and bandwidth to many folks who, just like me, expect Prettier to be a Swiss knife in the ream of the ever-pretty code! 😉

WDYT?

[j-f1]

How about changing --list-different’s behavior only when stdout is a TTY?

[lydell]

I’m in favor of adding a new, user-friendly --list-different alternative (along with documentation explaining the difference between the two). Then we can do CLI cleanups in a major version some time in the future.