Rename --output and --file flags for better understanding

[Dentrax]

What would you like to be added:

• --output -> --format
• --file -> --output

• Formats: syft-json cyclonedx-xml cyclonedx-json github github-json spdx-tag-value spdx-json table text
• Output: file to write the default report output to

Why is this needed:

It's a bit hard to distinguish both of --output and --file flags in the first place. output seems like "i want to write output to a file name arg0"; file is really hard to understand what it is for.

Additional context:
-

cc @developer-guy

[spiffcs]

Thanks @Dentrax! I suspect this is related to the conversations we're having here?
#1061

I'm a little hesitant to make this kind of breaking change even though we're pre v1.0 since it's a large shift from what we currently have as far as the CLI surface area and its interfaces. I do admit that I have my own biases about the current state of the flags
since I've been working on the tool a while.

cc @anchore/ci-tools-project if anyone wants to weigh in here since I don't have a great answer on 👍 or 👎 for this request.

[robparrott]

This makes a lot of sense to me. The current flags are confusing.

[joshbressers]

I agree the existing flags aren't ideal, but I think reusing one of them would create a horrible transition.

I think it would make more sense to create two new flags

--output-file
--output-format

Then in a few releases deprecate the --output and --file
Then if we want in the distant future, we could recycle --output

[spiffcs]

I'm good with the above proposal from @joshbressers with deprecation and eventual sunset of the old flags. @wagoodman since we're still pre v1 I don't think this would be the worst change, we just need to communicate via the tool the deprecated status for a couple of releases and then remove them.

[kzantow]

I think there's some misunderstanding about what the --output flag currently does, which may be confusing and we may want to revisit... but --output allows you to specify multiple instances of both an output format AND an output file, for example --output spdx-json=/path/to/file.spdx.json. If this is renamed to format in its current state, it would not be as correct. Now that there is a syft convert command, I would propose removing the multiple output option, so --output <format>[=file] would just go away, and at that point, --output could easily be renamed to --format, as far as I'm concerned. As for --file, I would agree with this being renamed to what seems to be more commonly referred to in CLIs as --output. I would not make these changes together, as @joshbressers noted: deprecate --output, transition to --format while removing the file option, and subsequently deprecate --file with a transition to --output. Just my 2c here.

[spiffcs]

I think first steps here is getting a readme update that clearly explains what Keith mentioned above. That will take away some of the confusion.

We keep --output and deprecate --file since --output has all the same functionality grouped together.

[tgerla]

Hey all, after some discussion we decided to try improving the --output help text and docs, and deprecate --file. You can of course still use shell redirection, too. Please see the related issues for Syft and Grype and if you have further comments, go ahead and put them there. Thanks!