On Wed, Apr 26, 2023 at 01:23:12PM -0700, Junio C Hamano wrote:
> Jacob Keller <jacob.e.keller@intel.com> writes:
> 
> >> Yeah, I'd be perfectly happy to rename this to `--format=porcelain`.
> >> I'll wait for the Review Club that discusses this patch set tomorrow and
> >> will send a new version with that change afterwards if nobody disagrees.
> >> 
> >> Patrick
> >
> > We had some discussion during review club about this, where the idea of
> > using "--porcelain" came up because many commands use that when
> > switching into a machine readable format.
> >
> > In addition, this format not only changes the output but also moves it
> > from being on stderr to stdout, which is a hint that the intended usage
> > of the command is now a little different.
> 
> A little different from what?  I do not think the answer would be
> "other program's --porcelain mode", as sending them to stdout would
> be one of the things that make the output easier for programs to
> parse, so it does sound like very much in the same spirit as "git
> status --porcelain" where its output format gets tweaked to be more
> machine friendly.
> 
> The output with "--porcelain" option enabled tend to be less human
> friendly and the distinction between Porcelain (for humans) and
> plumbing (for scripts) is reversed in the use of the word there---it
> started as "this is the option for those who write Porcelain
> commands to use", but still it is not a very good name for the
> option.

Ah, thanks for explaining where this reversed meaning actually comes
from. I really wondered why we use "porcelain" in preexisting code to
reflect machine-parseable interface, but that explanation does make
sense.

> I am perfectly OK if the plan is to uniformly use --output-format
> (or something equally more descriptive) and migrate and deprecate
> the "--porcelain" option away from existing commands.

I'm still not quite clear on where the consensus lies now. Personally, I
think that both `--format` and `--output-format` work well and are a bit
more descriptive than simply `--porcelain`, and wouldn't mind also
migrating other binaries to use either of them.

Furthermore, I think that `--[output-]format` has the advantage that you
don't need to handle priorities or mutual exclusion of different options
that all apply to the reference format. To a user, it is not immediately
obvious what `git fetch --format=compact --porcelain` would do, and
which of both options ultimately get respected. But that's likely only
true for future commands, because any migration would create the same
kind of ambiguity for preexisting commands.

If we were to also migrate preexisting code to use `--[output-]format`
then I'd argue that `--output-format` is likely the better name, mostly
because it is less likely to be ambiguous compared to `--format`. The
latter could e.g. easily confused with `--object-format`.

So I think I'll stick with `--output-format` for the time being.

Patrick