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@xxxxxxxxx> 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@xxxxxxxxx> >> >> > --- >> >> > 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...
