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.
next prev parent 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).