From: Teng Long <dyroneteng@gmail.com>
To: gitster@pobox.com
Cc: avarab@gmail.com, dyroneteng@gmail.com, git@vger.kernel.org,
sunshine@sunshineco.com, tenglong.tl@alibaba-inc.com
Subject: Re: [PATCH v5 3/3] notes.c: introduce "--separator" option
Date: Mon, 20 Feb 2023 22:00:46 +0800 [thread overview]
Message-ID: <20230220140046.16986-1-tenglong.tl@alibaba-inc.com> (raw)
In-Reply-To: <xmqq7cwhnql3.fsf@gitster.g>
Junio C Hamano <gitster@pobox.com> wrote on Thu, 16 Feb 2023 15:22:16 -0800:
> > When appending to a given notes object and the appended note is not
> > empty too, we will insert a blank line at first which separates the
> > existing note and the appended one, which as the separator.
>
> ", which as the separator" does not sound grammatically correct.
> Without that part, the above is a perfectly readable description of
> the current behaviour.
OK, I will remove ", which as the separator".
> > Sometimes, we want to use a specified <separator> as the separator. For
> > example, if we specify as:
> >
> > * --separator='------': we will insert "------\n" as the separator,
> > because user do not provide the line break char at last, we will add
> > the trailing '\n' compatibly.
>
> In a way compatible to what? I think s/compatibly// would be even
> easier to read. I think you are doing that for convenience.
My bad, I think I use a wrong word, maybe s/compatibly/automatically
and I look back and think the representation of "------\n" is not
correct, because "\n" is two characters here and will not treat
as a newline. So, after modification, maybe like:
* --separator='------': we will insert "------" and a trailing
newline character, because if no newline specified at the end,
one will be added automatically.
> > * --separator='------\n': we will insert as-is because it contains
> > the line break at last.
>
> If this behaviour gets spelled out like this, it needs to be
> justified.
>
> After seeing that "------" gives the user these dashes on its own
> single line, wouldn't a natural expectation by the user be to see a
> line with dashes, followed by a blank line, if you give "------\n"?
> How do you justify removal of that newline in a way that is easy to
> understand to readers?
>
> I am not saying that you should allow --separator="---\n\n\n" to
> give three blank lines between paragraphs. I think it makes sense to
> keep the stripspace in the code after a paragraph gets added. I just
> prefer to see it done as our design choice, not "because there is
> stripspace that removes them", i.e. what the code happens to do.
Firstly, like the problem I talked above, please let me figure out that
"------\n" is not represent as "------" and a blank line, but only
as "------\n" verbatim because "\n" will be treated as two characters
but not a blank line while parsing. If the user wants to specify a
blank line in the value of the option, they can pass "CTRL+v CTRL+j".
Then, I think I did get some interference from old logic. Returning
to the user scenario, I think about what the user needs and what is
my original idea is: consistent behavior
* behavior 1: What the user enters is used as the delimiter itself
without any special processing.
* behavior 2: No matter what the user enters, we always add a
newline at the end or other logic like stripspace, etc.
I prefer the first one, sometimes users want to be next to the previous
note, then:
git notes append -m foo -m bar --separator=""
and they can also choose to add as many line breaks as they want, then:
export LF="
"
git notes append -m foo -m bar --separator="$LF$LF$LF"
We didn't help users make choices but I have to say it may be a little
inconvenient to enter a newline character in the terminal, but I still
prefer this way.
> > * not specified --separator option: will use '\n' as the separator
> > when do appending and this is the default behavour.
>
> s/not specified --separator option/no --separator option/; the way
> you phrased can be misread for
>
Will apply as:
* no --separator option: will use '\n' as the separator when
do appending and this is the default behavour.
> git notes --separator -m foo -m bar
>
> i.e. any additional specifics is not given but --separator is still
> on the command line. But I do not think you meant that---rather
> this entry is what happens by default, i.e. a blank line separates
> each paragraph.
Yes, only separate the messages(-m), but not each paragraph in it.
> > * --separator='': we specify an empty separator which has the same
> > behavour with --separator='\n' and or not specified the option.
>
> I do not quite see why it is necessary to spell this out. Isn't
> this a natural consequence of the first one (i.e. "six dashes
> without any terminating LF gets a line with dashes plus LF"
> naturally extends to "0 dashes without any terminating LF gets a
> blank line")?
Agree.. will remove.
> > In addition, if a user specifies multple "-m" with "--separator", the
> > separator should be inserted between the messages too, so we use
> > OPT_STRING_LIST instead of OPT_CALLBACK_F to parse "-m" option, make
> > sure the option value of "--separator" been parsed already when we need
> > it.
>
> This is hard to grok. Is it an instruction to whoever is
> implementing this new feature, or is it an instruct to end-users
> telling that they need to give --separator before they start giving
> -m <msg>, -F <file>, -c <object>, etc.?
No, it's not the order of the user give, but the backend we deal.
We use "parse_msg_arg" as a callback when parsing "-m " by OPT_CALLBACK_F,
so if we have to read the separator before we parse it, so we could insert
it correctly between the messages, So I use OPT_STRING_LIST instead.
> > diff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt
> > index efbc10f0..5abe6092 100644
> > --- a/Documentation/git-notes.txt
> > +++ b/Documentation/git-notes.txt
> > @@ -11,7 +11,7 @@ SYNOPSIS
> > 'git notes' [list [<object>]]
> > 'git notes' add [-f] [--allow-empty] [-F <file> | -m <msg> | (-c | -C) <object>] [<object>]
>
> Doesn't add allow you to say
>
> $ git notes add -m foo -m bar
>
> Shouldn't it also honor --separator to specify an alternate
> paragraph break?
Agree, you also mentioned me that, does git-notes-add need to be implies by
this option too? I think it needs too.
> > @@ -86,7 +86,9 @@ the command can read the input given to the `post-rewrite` hook.)
> >
> > append::
> > Append to the notes of an existing object (defaults to HEAD).
> > - Creates a new notes object if needed.
> > + Creates a new notes object if needed. If the note and the
> > + message are not empty, "\n" will be inserted between them.
> > + Use the `--separator` option to insert other delimiters.
>
> "\n" is so, ... programmer lingo? "A blank line" is inserted
> between these paragraphs.
Will apply.
> > +--separator <separator>::
> > + The '<separator>' inserted between the note and message
> > + by 'append', "\n" by default. A custom separator can be
>
> I see no reason to single out 'append'; "add -m <msg> -m <msg>"
> follows exactly the same paragraph concatenation logic in the
> current code, no? If we allow customized paragraph separators,
> we should use the same logic there as well.
Agree, as I replied above, I think it will be done in next patch.
> It probably is simpler to explain if you treat the "current note in
> 'append'" as if the text were just "earlier paragraphs", to which
> more paragraphs taken from each -m <msg> and -F <file> are
> concatenated, with paragraph break before each of them. In the case
> of 'add', there happens to be zero "earlier paragraphs", but
> everything else gets concatenated the same way, no?
Yes, they are the same way, you are right, so we should let add and append
both be implied by the option.
> > + provided, if it doesn't end in a "\n", one will be added
> > + implicitly .
>
> Funny punctuation.
My bad, will fix.
Thanks very much for your detailed review.
next prev parent reply other threads:[~2023-02-20 14:01 UTC|newest]
Thread overview: 186+ messages / expand[flat|nested] mbox.gz Atom feed top
2022-10-13 5:56 [RFC PATCH 0/2] notes.c: introduce "--no-blankline" option Teng Long
2022-10-13 5:56 ` [RFC PATCH 1/2] " Teng Long
2022-10-13 6:06 ` Junio C Hamano
2022-10-17 13:19 ` Teng Long
2022-10-13 9:31 ` Ævar Arnfjörð Bjarmason
2022-10-17 13:33 ` Teng Long
2022-10-13 5:56 ` [RFC PATCH 2/2] notes.c: fixed tip when target and append note are both empty Teng Long
2022-10-13 9:36 ` Ævar Arnfjörð Bjarmason
2022-10-13 10:10 ` Phillip Wood
2022-10-13 10:23 ` Ævar Arnfjörð Bjarmason
2022-10-15 19:40 ` Phillip Wood
2022-10-18 3:25 ` Teng Long
2022-10-18 8:08 ` Teng Long
2022-10-18 3:11 ` Teng Long
2022-10-18 9:23 ` Ævar Arnfjörð Bjarmason
2022-11-07 13:57 ` [PATCH v2 0/3] notes.c: introduce "--blank-line" option Teng Long
2022-11-07 13:57 ` [PATCH v2 1/3] " Teng Long
2022-11-07 14:45 ` Ævar Arnfjörð Bjarmason
2022-11-07 15:45 ` Eric Sunshine
2022-11-07 17:22 ` Ævar Arnfjörð Bjarmason
2022-11-07 21:46 ` Taylor Blau
2022-11-07 22:36 ` Ævar Arnfjörð Bjarmason
2022-11-08 0:32 ` Taylor Blau
2022-11-08 3:45 ` Teng Long
2022-11-08 13:06 ` Teng Long
2022-11-08 13:22 ` Ævar Arnfjörð Bjarmason
2022-11-09 6:35 ` Teng Long
2022-11-07 15:06 ` Ævar Arnfjörð Bjarmason
2022-11-08 6:32 ` Teng Long
2022-11-07 21:47 ` Taylor Blau
2022-11-08 7:36 ` Teng Long
2022-11-07 13:57 ` [PATCH v2 2/3] notes.c: fixed tip when target and append note are both empty Teng Long
2022-11-07 14:40 ` Ævar Arnfjörð Bjarmason
2022-11-07 21:51 ` Taylor Blau
2022-11-07 22:33 ` Ævar Arnfjörð Bjarmason
2022-11-07 22:45 ` Taylor Blau
2022-11-08 8:55 ` Teng Long
2022-11-07 13:57 ` [PATCH v2 3/3] notes.c: drop unreachable code in "append_edit()" Teng Long
2022-11-07 14:41 ` Ævar Arnfjörð Bjarmason
2022-11-07 14:57 ` [PATCH v2 0/3] notes.c: introduce "--blank-line" option Ævar Arnfjörð Bjarmason
2022-11-09 7:05 ` Teng Long
2022-11-09 7:06 ` Teng Long
2022-11-09 9:06 ` [PATCH v3 0/5] notes.c: introduce "--no-blank-line" option Teng Long
2022-11-09 9:06 ` [PATCH v3 1/5] notes.c: cleanup 'strbuf_grow' call in 'append_edit' Teng Long
2022-11-09 9:06 ` [PATCH v3 2/5] notes.c: cleanup for "designated init" and "char ptr init" Teng Long
2022-11-09 9:06 ` [PATCH v3 3/5] notes.c: drop unreachable code in 'append_edit()' Teng Long
2022-11-09 9:06 ` [PATCH v3 4/5] notes.c: provide tips when target and append note are both empty Teng Long
2022-11-09 9:06 ` [PATCH v3 5/5] notes.c: introduce "--no-blank-line" option Teng Long
2022-11-28 14:20 ` [PATCH v3 0/5] " Teng Long
2022-11-29 1:10 ` Junio C Hamano
2022-11-29 22:53 ` Taylor Blau
2022-11-29 12:57 ` Teng Long
2022-11-29 13:19 ` Junio C Hamano
2022-12-15 12:48 ` Teng Long
2022-12-19 3:03 ` Eric Sunshine
2022-12-21 9:16 ` Teng Long
2022-12-21 11:35 ` Junio C Hamano
2022-12-22 9:30 ` Teng Long
2022-12-23 1:36 ` Eric Sunshine
2023-01-12 2:48 ` [PATCH v4 0/5] notes.c: introduce "--separator" optio Teng Long
2023-01-12 2:48 ` [PATCH v4 1/5] notes.c: cleanup 'strbuf_grow' call in 'append_edit' Teng Long
2023-01-15 4:53 ` Eric Sunshine
2023-01-28 11:22 ` Teng Long
2023-01-12 2:48 ` [PATCH v4 2/5] notes.c: cleanup for "designated init" and "char ptr init" Teng Long
2023-01-12 9:51 ` Ævar Arnfjörð Bjarmason
2023-01-28 11:33 ` Teng Long
2023-01-12 2:48 ` [PATCH v4 3/5] notes.c: drop unreachable code in 'append_edit()' Teng Long
2023-01-15 20:59 ` Eric Sunshine
2023-01-15 21:10 ` Eric Sunshine
2023-01-28 11:50 ` Teng Long
2023-01-30 5:38 ` Eric Sunshine
2023-02-01 8:08 ` Teng Long
2023-01-12 2:48 ` [PATCH v4 4/5] notes.c: provide tips when target and append note are both empty Teng Long
2023-01-12 9:52 ` Ævar Arnfjörð Bjarmason
2023-01-15 21:28 ` Eric Sunshine
2023-01-12 2:48 ` [PATCH v4 5/5] notes.c: introduce "--separator" option Teng Long
2023-01-12 9:53 ` Ævar Arnfjörð Bjarmason
2023-01-15 22:04 ` Eric Sunshine
2023-01-15 22:15 ` Eric Sunshine
2023-02-16 13:05 ` [PATCH v5 0/3] " Teng Long
2023-02-16 13:05 ` [PATCH v5 1/3] notes.c: cleanup 'strbuf_grow' call in 'append_edit' Teng Long
2023-02-16 18:39 ` Junio C Hamano
2023-02-20 3:34 ` Teng Long
2023-02-16 13:05 ` [PATCH v5 2/3] notes.c: cleanup for "designated init" Teng Long
2023-02-16 18:39 ` Junio C Hamano
2023-02-16 13:05 ` [PATCH v5 3/3] notes.c: introduce "--separator" option Teng Long
2023-02-16 23:22 ` Junio C Hamano
2023-02-20 14:00 ` Teng Long [this message]
2023-02-21 21:31 ` Junio C Hamano
2023-02-22 8:17 ` Teng Long
2023-02-22 23:15 ` Junio C Hamano
2023-02-23 7:29 ` [PATCH v6 0/3] " Teng Long
2023-02-23 7:29 ` [PATCH v6 1/3] notes.c: cleanup 'strbuf_grow' call in 'append_edit' Teng Long
2023-02-23 7:29 ` [PATCH v6 2/3] notes.c: cleanup for "designated init" Teng Long
2023-02-23 7:29 ` [PATCH v6 3/3] notes.c: introduce '--separator=<paragraph-break>' option Teng Long
2023-02-23 18:21 ` Junio C Hamano
2023-02-28 14:11 ` Teng Long
2023-02-25 21:30 ` Junio C Hamano
2023-02-28 14:14 ` Teng Long
2023-03-27 13:13 ` [PATCH v6 0/3] notes.c: introduce "--separator" option Teng Long
2023-03-28 14:28 ` [PATCH v7 0/4] " Teng Long
2023-03-28 14:28 ` [PATCH v7 1/4] notes.c: cleanup 'strbuf_grow' call in 'append_edit' Teng Long
2023-03-28 14:28 ` [PATCH v7 2/4] notes.c: cleanup for "designated init" Teng Long
2023-03-29 22:17 ` Junio C Hamano
2023-03-28 14:28 ` [PATCH v7 3/4] notes.c: introduce '--separator=<paragraph-break>' option Teng Long
2023-03-28 15:37 ` Junio C Hamano
2023-03-29 14:15 ` Teng Long
2023-03-29 21:48 ` Junio C Hamano
2023-04-13 9:36 ` Teng Long
2023-03-28 14:28 ` [PATCH v7 4/4] notes.c: don't do stripespace when parse file arg Teng Long
2023-03-28 15:54 ` Junio C Hamano
2023-03-29 12:06 ` Teng Long
2023-03-29 16:21 ` Junio C Hamano
2023-04-25 13:34 ` [PATCH 0/6] notes.c: introduce "--separator" option Teng Long
2023-04-25 13:34 ` [PATCH v8 1/6] notes.c: cleanup 'strbuf_grow' call in 'append_edit' Teng Long
2023-04-25 13:34 ` [PATCH v8 2/6] notes.c: use designated initializers for clarity Teng Long
2023-04-25 13:34 ` [PATCH v8 3/6] t3321: add test cases about the notes stripspace behavior Teng Long
2023-04-25 16:25 ` Junio C Hamano
2023-04-27 3:47 ` Teng Long
2023-04-25 13:34 ` [PATCH v8 4/6] notes.c: introduce '--separator=<paragraph-break>' option Teng Long
2023-04-25 17:34 ` Junio C Hamano
2023-04-27 7:21 ` Teng Long
2023-04-27 18:21 ` Junio C Hamano
2023-04-25 17:35 ` Junio C Hamano
2023-04-25 13:34 ` [PATCH v8 5/6] notes.c: append separator instead of insert by pos Teng Long
2023-04-25 17:47 ` Junio C Hamano
2023-04-27 7:51 ` Teng Long
2023-04-25 13:34 ` [PATCH v8 6/6] notes.c: introduce "--[no-]stripspace" option Teng Long
2023-04-25 17:49 ` Junio C Hamano
2023-04-28 7:40 ` Teng Long
2023-04-28 18:21 ` Junio C Hamano
2023-04-28 9:23 ` [PATCH v9 0/6] notes.c: introduce "--separator" option Teng Long
2023-04-28 9:23 ` [PATCH v9 1/6] notes.c: cleanup 'strbuf_grow' call in 'append_edit' Teng Long
2023-04-28 9:23 ` [PATCH v9 2/6] notes.c: use designated initializers for clarity Teng Long
2023-04-28 9:23 ` [PATCH v9 3/6] t3321: add test cases about the notes stripspace behavior Teng Long
2023-04-28 9:23 ` [PATCH v9 4/6] notes.c: introduce '--separator=<paragraph-break>' option Teng Long
2023-04-28 20:44 ` Junio C Hamano
2023-05-06 9:12 ` Teng Long
2023-05-06 9:22 ` Teng Long
2023-05-10 19:19 ` Kristoffer Haugsbakk
2023-05-12 4:07 ` Teng Long
2023-05-12 7:29 ` Kristoffer Haugsbakk
2023-05-16 17:00 ` Junio C Hamano
2023-05-17 3:58 ` Teng Long
2023-05-17 15:32 ` Junio C Hamano
2023-06-14 1:02 ` Junio C Hamano
2023-06-14 1:10 ` [PATCH] notes: do not access before the beginning of an array Junio C Hamano
2023-06-14 1:41 ` [PATCH v9 4/6] notes.c: introduce '--separator=<paragraph-break>' option Eric Sunshine
2023-06-14 2:07 ` Junio C Hamano
2023-06-15 7:13 ` Jeff King
2023-06-15 19:15 ` Junio C Hamano
2023-06-19 6:08 ` Teng Long
2023-06-20 20:36 ` Junio C Hamano
2023-06-21 2:50 ` Teng Long
2023-04-28 9:23 ` [PATCH v9 5/6] notes.c: append separator instead of insert by pos Teng Long
2023-04-28 9:23 ` [PATCH v9 6/6] notes.c: introduce "--[no-]stripspace" option Teng Long
2023-04-28 20:46 ` [PATCH v9 0/6] notes.c: introduce "--separator" option Junio C Hamano
2023-05-01 22:29 ` Junio C Hamano
2023-05-18 12:02 ` [PATCH v10 " Teng Long
2023-05-18 12:02 ` [PATCH v10 1/6] notes.c: cleanup 'strbuf_grow' call in 'append_edit' Teng Long
2023-05-18 12:02 ` [PATCH v10 2/6] notes.c: use designated initializers for clarity Teng Long
2023-05-18 12:02 ` [PATCH v10 3/6] t3321: add test cases about the notes stripspace behavior Teng Long
2023-05-18 12:02 ` [PATCH v10 4/6] notes.c: introduce '[--[no-]separator|--separator=<paragraph-break>]' option Teng Long
2023-05-18 14:34 ` Kristoffer Haugsbakk
2023-05-20 10:41 ` Teng Long
2023-05-20 16:12 ` Kristoffer Haugsbakk
2023-05-19 0:54 ` Jeff King
2023-05-27 7:17 ` Teng Long
2023-05-27 17:19 ` Jeff King
2023-05-29 11:48 ` Teng Long
2023-05-18 12:02 ` [PATCH v10 5/6] notes.c: append separator instead of insert by pos Teng Long
2023-05-18 12:02 ` [PATCH v10 6/6] notes.c: introduce "--[no-]stripspace" option Teng Long
2023-05-18 13:56 ` [PATCH v10 0/6] notes.c: introduce "--separator" option Kristoffer Haugsbakk
2023-05-20 10:22 ` Teng Long
2023-05-18 15:17 ` Junio C Hamano
2023-05-20 10:59 ` Teng Long
2023-05-27 7:57 ` [PATCH v11 0/7] notes.c: introduce "--separator" Teng Long
2023-05-27 7:57 ` [PATCH v11 1/7] notes.c: cleanup 'strbuf_grow' call in 'append_edit' Teng Long
2023-05-27 7:57 ` [PATCH v11 2/7] notes.c: use designated initializers for clarity Teng Long
2023-05-27 7:57 ` [PATCH v11 3/7] t3321: add test cases about the notes stripspace behavior Teng Long
2023-05-27 7:57 ` [PATCH v11 4/7] notes.c: introduce '--separator=<paragraph-break>' option Teng Long
2023-05-27 7:57 ` [PATCH v11 5/7] notes.c: append separator instead of insert by pos Teng Long
2023-05-27 7:57 ` [PATCH v11 6/7] notes.c: introduce "--[no-]stripspace" option Teng Long
2023-05-27 7:57 ` [PATCH v11 7/7] notes: introduce "--no-separator" option Teng Long
2023-06-01 5:50 ` [PATCH v11 0/7] notes.c: introduce "--separator" Junio C Hamano
2023-06-03 10:01 ` Teng Long
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
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20230220140046.16986-1-tenglong.tl@alibaba-inc.com \
--to=dyroneteng@gmail.com \
--cc=avarab@gmail.com \
--cc=git@vger.kernel.org \
--cc=gitster@pobox.com \
--cc=sunshine@sunshineco.com \
--cc=tenglong.tl@alibaba-inc.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.
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).