Consider renaming --format to --report

[mre]

With our recent introduction of the --mode option in #1398, some CLI calls can get confusing:

lychee --no-progress --mode emoji --format detailed https://example.com

The format parameter is simply for the report format, so I propose to rename it to --report to make its usage clear:

lychee --no-progress --mode emoji --report detailed https://example.com

This is a breaking change, but we haven't published a stable release yet, so it's okay according to semver.
It will still cause some disruption for downstream users, but I'd say it's better to change it sooner rather than later.

I'm open for suggestions, though. Maybe it's just a personal issue.

[thomas-zahner]

Hmm, not quite sure if this is much clearer. The parameter is used to configure the output format. So why not name it --output-format? Or maybe there are other tools with a comparable option, maybe they have a better name?

  -f, --format <FORMAT>
          Output format of final status report (compact, detailed, json, markdown) [default: compact]

[mre]

I like it, but technically, it's just about the output format of the final status report, right? 🤔 I wanted to clarify that part and shift the focus to the actual data format (Markdown, JSON) instead.

I'm suggesting --report-format as well.

Alternatively, we can keep --format if it's not too confusing.

[thomas-zahner]

Well yes I also like --report-format. But I actually think that format is not too confusing and I like its simplicity. IMO we can keep it.

Also thought about naming it --output but then I realised that this option already exists. And now I'm wondering why that option even exits. I think that this option has become useless since #984 was released. Because redirecting stdout should be equivalent to the --output option. Or am I missing something?

[mre]

Yeah, probably --format is equally good/bad compared to the other options. In light of that, let's keep it. The discussion was still fruitful, because we can refer to it the next time this question comes up.

--output is redundant, as you said. I'd still like to keep it, because people might not have a clear expectation about what redirecting stdout would entail. We know that we redirect errors to stderr, but not all projects do so, and that might be a source of confusion.
That said, --output is a misleading, too, because it doesn't imply that it's about writing the output to a file. Perhaps --output-file might be less
ambiguous. Then again, --output is shorter and more concise. Naming things is hard.

I propose to close this issue as "won't fix". We can always open a new issue for the --output option if we find that it's causing confusion.

[thomas-zahner]

I totally agree 👍