git@vger.kernel.org mailing list mirror (one of many)
 help / color / mirror / code / Atom feed
From: "Ævar Arnfjörð Bjarmason" <avarab@gmail.com>
To: Sergey Organov <sorganov@gmail.com>
Cc: git@vger.kernel.org, Jeff King <peff@peff.net>
Subject: Re: changing the experimental 'git switch'
Date: Tue, 26 Oct 2021 00:23:29 +0200	[thread overview]
Message-ID: <211026.86sfwo20kr.gmgdl@evledraar.gmail.com> (raw)
In-Reply-To: <87h7d5yrxy.fsf@osv.gnss.ru>


On Mon, Oct 25 2021, Sergey Organov wrote:

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

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

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.

  reply	other threads:[~2021-10-25 22:37 UTC|newest]

Thread overview: 58+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2021-10-21 11:55 Notes from the Git Contributors' Summit 2021, virtual, Oct 19/20 Johannes Schindelin
2021-10-21 11:55 ` [Summit topic] Crazy (and not so crazy) ideas Johannes Schindelin
2021-10-21 12:30   ` Son Luong Ngoc
2021-10-26 20:14   ` scripting speedups [was: [Summit topic] Crazy (and not so crazy) ideas] Eric Wong
2021-10-30 19:58     ` Ævar Arnfjörð Bjarmason
2021-11-03  9:24       ` test suite speedups via some not-so-crazy ideas (was: scripting speedups[...]) Ævar Arnfjörð Bjarmason
2021-11-03 22:12         ` test suite speedups via some not-so-crazy ideas Junio C Hamano
2021-11-02 13:52     ` scripting speedups [was: [Summit topic] Crazy (and not so crazy) ideas] Johannes Schindelin
2021-10-21 11:55 ` [Summit topic] SHA-256 Updates Johannes Schindelin
2021-10-21 11:56 ` [Summit topic] Server-side merge/rebase: needs and wants? Johannes Schindelin
2021-10-22  3:06   ` Bagas Sanjaya
2021-10-22 10:01     ` Johannes Schindelin
2021-10-23 20:52       ` Ævar Arnfjörð Bjarmason
2021-11-08 18:21   ` Taylor Blau
2021-11-09  2:15     ` Ævar Arnfjörð Bjarmason
2021-11-30 10:06       ` Christian Couder
2021-10-21 11:56 ` [Summit topic] Submodules and how to make them worth using Johannes Schindelin
2021-10-21 11:56 ` [Summit topic] Sparse checkout behavior and plans Johannes Schindelin
2021-10-21 11:56 ` [Summit topic] The state of getting a reftable backend working in git.git Johannes Schindelin
2021-10-25 19:00   ` Han-Wen Nienhuys
2021-10-25 22:09     ` Ævar Arnfjörð Bjarmason
2021-10-26  8:12       ` Han-Wen Nienhuys
2021-10-28 14:17         ` Philip Oakley
2021-10-26 15:51       ` Philip Oakley
2021-10-21 11:56 ` [Summit topic] Documentation (translations, FAQ updates, new user-focused, general improvements, etc.) Johannes Schindelin
2021-10-22 14:20   ` Jean-Noël Avila
2021-10-22 14:31     ` Ævar Arnfjörð Bjarmason
2021-10-27  7:02       ` Jean-Noël Avila
2021-10-27  8:50       ` Jeff King
2021-10-21 11:56 ` [Summit topic] Increasing diversity & inclusion (transition to `main`, etc) Johannes Schindelin
2021-10-21 12:55   ` Son Luong Ngoc
2021-10-22 10:02     ` vale check, was " Johannes Schindelin
2021-10-22 10:03       ` Johannes Schindelin
2021-10-21 11:57 ` [Summit topic] Improving Git UX Johannes Schindelin
2021-10-21 16:45   ` changing the experimental 'git switch' (was: [Summit topic] Improving Git UX) Ævar Arnfjörð Bjarmason
2021-10-21 23:03     ` changing the experimental 'git switch' Junio C Hamano
2021-10-22  3:33     ` changing the experimental 'git switch' (was: [Summit topic] Improving Git UX) Bagas Sanjaya
2021-10-22 14:04     ` martin
2021-10-22 14:24       ` Ævar Arnfjörð Bjarmason
2021-10-22 15:30         ` martin
2021-10-23  8:27           ` changing the experimental 'git switch' Sergey Organov
2021-10-22 21:54         ` Sergey Organov
2021-10-24  6:54       ` changing the experimental 'git switch' (was: [Summit topic] Improving Git UX) Martin
2021-10-24 20:27         ` changing the experimental 'git switch' Junio C Hamano
2021-10-25 12:48           ` Ævar Arnfjörð Bjarmason
2021-10-25 17:06             ` Junio C Hamano
2021-10-25 16:44     ` Sergey Organov
2021-10-25 22:23       ` Ævar Arnfjörð Bjarmason [this message]
2021-10-27 18:54         ` Sergey Organov
2021-10-21 11:57 ` [Summit topic] Improving reviewer quality of life (patchwork, subsystem lists?, etc) Johannes Schindelin
2021-10-21 13:41   ` Konstantin Ryabitsev
2021-10-22 22:06     ` Ævar Arnfjörð Bjarmason
2021-10-22  8:02 ` Missing notes, was Re: Notes from the Git Contributors' Summit 2021, virtual, Oct 19/20 Johannes Schindelin
2021-10-22  8:22   ` Johannes Schindelin
2021-10-22  8:30     ` Johannes Schindelin
2021-10-22  9:07       ` Johannes Schindelin
2021-10-22  9:44 ` Let's have public Git chalk talks, " Johannes Schindelin
2021-10-25 12:58   ` Ævar Arnfjörð Bjarmason

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

  List information: http://vger.kernel.org/majordomo-info.html

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=211026.86sfwo20kr.gmgdl@evledraar.gmail.com \
    --to=avarab@gmail.com \
    --cc=git@vger.kernel.org \
    --cc=peff@peff.net \
    --cc=sorganov@gmail.com \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
Code repositories for project(s) associated with this public inbox

	https://80x24.org/mirrors/git.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).