On Mon, Oct 25 2021, Sergey Organov wrote: > Ævar Arnfjörð Bjarmason <avarab@xxxxxxxxx> 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.... > 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@xxxxxxxxxxxxxxxxxxx/ 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.
