Re: [PATCH v3 4/4] scalar reconfigure: add --maintenance=<mode> option

From: Junio C Hamano <gitster@pobox.com>
Date: May 14, 2025, 12:28 UTC
Message-ID: <xmqqzfffcr5j.fsf@gitster.g>
In-Reply-To: <82c2c073-3fa6-4023-82d5-bdb772c3790b@gmail.com>

Derrick Stolee <stolee@gmail.com> writes:

Show 13 quoted lines

>> As you suggested in a part of your response I omitted, we can
>> annotate <mode> to give hints on the valid choices to help users,
>> without changing the default behaviour.  I am personally fine either
>> way, as long as we clearly document the reasoning behind our design.
>
> I'll create a new patch on top of the current series version that
> does this, calling it out as an intentional pattern. It's previously
> been used by these examples:
>
>  * --fixup=[(amend|reword):]<commit>
>  * --diff-filter=[(A|C|D|M|R|T|U|X|B)...[*]]
>  * --tool=[g,n,]vimdiff
>  * --exclude-hidden=[fetch|receive|uploadpack]

Yup, these are good things to have in "git cmd -h" to help users jog their memory what the available choices are. We do not have to always verbosely explain what these mean everywhere, of course, but if we said in "git commit -h" something like

    --fixup=<choice>

that would be almost hostile to the users. And in documentation pages, of course we can describe what each of the available choices mean.

Show 5 quoted lines

> One place where this kind of notation could be helpful, but appears
> to be absent, is the '-L(<n>:<m>)|(:<method>):<file>' argument for
> 'git log' and 'git rev-list'. Perhaps this is too dense, though, so
> it would be better split into '-L<n>:<m>:<file>' and
> '-L:<method>:<file>'.

Yup.