Re: changing the experimental 'git switch'

From: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
Date: Oct 25, 2021, 22:23 UTC
Message-ID: <211026.86sfwo20kr.gmgdl@evledraar.gmail.com>
In-Reply-To: <87h7d5yrxy.fsf@osv.gnss.ru>

On Mon, Oct 25 2021, Sergey Organov wrote:

Show 18 quoted lines

> Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes:
>
> [...]
>
>> 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....

Show 17 quoted lines

> 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).

Show 6 quoted lines

> 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.

Show 10 quoted lines

> 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/

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.