Re: [PATCH v2 1/3] notes.c: introduce "--blank-line" option

["Ævar Arnfjörð Bjarmason" <avarab@gmail.com>]

On Mon, Nov 07 2022, Taylor Blau wrote:

> On Mon, Nov 07, 2022 at 06:22:34PM +0100, Ævar Arnfjörð Bjarmason wrote:
>>
>> On Mon, Nov 07 2022, Eric Sunshine wrote:
>>
>> > On Mon, Nov 7, 2022 at 9:56 AM Ævar Arnfjörð Bjarmason <avarab@gmail.com> wrote:
>> >> On Mon, Nov 07 2022, Teng Long wrote:
>> >> > When appending to a given object which has note and if the appended
>> >> > note is not empty too, we will insert a blank line at first. The
>> >> > blank line serves as a split line, but sometimes we just want to
>> >> > omit it then append on the heels of the target note. So, we add
>> >> > a new "OPT_BOOL()" option to determain whether a new blank line
>> >> > is insert at first.
>> >> >
>> >> > Signed-off-by: Teng Long <dyroneteng@gmail.com>
>> >> > ---
>> >> > diff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt
>> >> > @@ -159,6 +161,11 @@ OPTIONS
>> >> > +--blank-line::
>> >> > +--no-blank-line::
>> >> > +     Controls if a blank line to split paragraphs is inserted
>> >> > +     when appending (the default is true).
>> >>
>> >> Just make this:
>> >>
>> >>         --no-blank-line:
>> >>                 Suppress the insertion of a blank line before the
>> >>                 inserted notes.
>> >>
>> >> Or something, i.e. when adding a "true by default" let's add a "no-..." variant directly.
>> >
>> > This is the exact opposite of Junio's advice[1], isn't it?
>> >
>> > [1]: https://lore.kernel.org/git/xmqqsfjsi7eq.fsf@gitster.g/
>>
>> I read that as him mainly talking about what we name the variable (which
>> I agree with, but didn't comment on here). I'm talking about what
>> interface is exposed to the user.
>
> Having --blank-line as an option is convenient for scripting, so I'd err
> on the side of the original interpretation of Junio's suggestion.

I see from re-reading my reply that I was conflating two things. What I
*meant* to suggest is this:

When an option is not the default, and we provide a way to turn it off
we usually document that as:

	--no-foo:
		Don't do foo.

See e.g. "git commit --no-edit", and "git clone --no-checkout".

But this is orthagonal to what you call the option in the source, and
whether your variable is "inverted". I.e. in both those cases we have a
"--edit" and "--checkout", but when we prepare the options for
parse_options() we do (or the equivalent of):

	int no_checkout = 0;
	OPT_BOOL('n', "no-checkout", &option_no_checkout,

And:

	int edit = 1;
	OPT_BOOL('e', "edit", &edit_flag, N_("force edit of commit")),

So, I'm (now) saying I don't care which form we use in the sources, but
that' it's useful to document things as e.g.:

	--no-checkout::
        	No checkout of HEAD is performed after the clone is complete.

Instead of e.g.:

	--no-checkout:
	--checkout:
 		Do we do a checkout when we clone (doing a checkout is
 		the default).

Because the former convention shows the user at a glance which of the
two is the default.

> We can clearly support '--[no-]blank-line' and allow latter arguments to
> override previous ones.

We'll support both either way, i.e. parse_options() detects that the
name starts with "no-", so the negation of a "no-checkout" isn't
"--no-no-checkout", but a "--checkout".

> The documentation is fine as-is.

I think the above form would make it a bit better, but just my 0.02:

	--no-blank-line::
		Don't add an extra "\n" between the body of the commit
		and the note.

Or something...