Re: changing the experimental 'git switch'

On Mon, Oct 25 2021, Sergey Organov wrote:

Ævar Arnfjörð Bjarmason [off-list ref] writes:

[...]

quoted

I really don't know, but I do think that the most viable path to a
better UX for git is to consider its UX more holistically.

To the extent that our UX is a mess I think it's mainly because we've
ended up with an accumulation of behavior that made sense in isolation
at the time, but which when combined presents bad or inconsistent UX to
the user.

Yep. Moreover, this practice of "making sense" being the primary
reasoning factor doesn't work very well even in isolation, for single
Git sub-commands. As there is no defined underlying UI model, or rules,
or even clear guidelines of how to properly design command-line options,
multiple authors, all having their own sense and having no common ground
to base their decisions on, inevitably produce some spaghetti UI.

Yes we're definitely lacking on the documentation front here at least,
but I do think we have quite a bit of consistency in the form of
parse_options() users....

The UI model to be defined, provided we are serious about aiming at a
good design, in fact has at least 2 aspects to address:

1. Uniform top-level syntax of all the Git commands.

have have e.g. hash-object but nothing like hash_object, there's that at
least..., but also mktag, not make-tag, so....

2. Uniform rules to handle command-line options.

Being hard to produce simple yet flexible design by itself, the problem
is further complicated by the need to absorb as much of the existing UI
as reasonably possible.

Once a model is defined though, we should be able to at least ensure new
designs fit the model, and then, over time, gradually replace legacy UIs
that currently don't fit.

As a side-note, from this standpoint, discussing deep details of "git
switch" options, or even relevancy of introducing of "git switch" in the
first place, has still no proper ground.

Not even touching (1) for now, let me put some feelers out to see if we
can even figure how the rules or guidelines for command-line options
design may look like.

Having hacked quite a bit on parse_options() recently, including quite a
bit of unsubmitted work I've got some opinions in this area :)

That API is as close as we get to uniform UX in this area.

1. All options are divided into 2 classes: basic options and convenience
   options.

Are you thinking of things like "git config --bool" v.s. "git config
--type=bool" (let's ignore that we discourage the former for now), or
more like "common" v.s. "obscure" ?

2. Minimalism. Every basic option should tweak exactly one aspect of
   program behavior.

Generally, although for things like "git log" you quickly end up with
wanting to have pseudo-mode options imply one thing or the other,
sometimes for the better, sometimes wfor worse.

3. Orthogonality. Every basic option should not "imply" any other
   option, nor change the behavior of any other option.

Yeah, generally.

4. Reversibility. Every basic option should have a way to set it to any
   supported value at any moment, including setting it back to its
   default value.

Yeah, for sure, we're generally quite good at this with parse_options(),
but there's exceptions (particularly with callbacks).

5. Grouping for convenience. A convenience option (usually with a short
   syntax), should be semantically equivalent to an exact sequence of
   basic options, as if it were substituted at the place of the
   convenience option, and should not otherwise tweak program behavior.
   I.e., a convenience option should be simple textual synonym for
   particular sequence of basic options.

I think some examples for the above in terms of current git commands
would be quite helpful, I'm struggling to think of examples for some of
these.

Please notice that in the above model basic option having a short form
is formally considered to be a short convenience option that is a
synonym for long basic option.

There are obviously some other useful guidelines that could be defined,
or some alternate approach could be chosen,but the primary point is that
if we want a consistent UI, we do need some rules, and we need
convenient implementation of the model agreed upon, and then ensure that
from all the designs that "make sense", only those that fit into
underlying model are accepted.

There was a recent discussion about cat-file option parsing semantics at
https://lore.kernel.org/git/87tuhuikhf.fsf@evledraar.gmail.com/ (local)

I have this unsubmitted (and updated from that discussion) patch to make
"cat-file" help friendlier:
https://github.com/avar/git/commit/bd32f57cd21

I wonder what you think abut that new output v.s. the old.

More generally, I've wanted to have some mode for parse_options() for a
while now to label a given option X as only going with option. We have
OPT_CMDMODE() for things that are mutually exclusive with all other
options, but not anything like a OPT_SUBCMDMODE() or whatever (and
sometimes such a thing would go with N "top-level modes", not just one).

Right now you need to do that manually, see the usage_msg_opt[f]()
verbosity at:
https://github.com/avar/git/blob/avar/cat-file-usage-and-options-handling/builtin/cat-file.c#L679-L755

I thing like that would be really useful, and would go a long way
towards consistent UX, as you could generate the sort of "grouped help"
shown in the commit link above with it, as well as have things like:

    git some-command --top-level-option --op<TAB>

Tab-complete only those --op* options that go with that
--top-level-option.

I guess what I'm saying is that I agree with you, but just think that
incremental changes to these UX APIs is the most viable way forward.