[PATCH 0/6] doc: --stdin on notes and core.commentChar mentions

[PATCH 0/6] doc: --stdin on notes and core.commentChar mentions

[kristofferhaugsbakk]

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

I wanted to fix `--stdin` in the git-notes(1) documentation.  Then I
found some other things on that doc as well as things to do with
`core.commentChar`.

I was unsure how I should refer to the config since `core.commentChar`
and `core.commentString` are aliases.  I just went with the first since
no other docs mention the second.

§ CC

Peff: for 9ccf3e9b22b (config: add core.commentString, 2024-03-27)

Teng Long: for 3d6a3164649 (notes: introduce "--no-separator" option,
2023-05-27)

Kristoffer Haugsbakk (6):
  doc: stripspace: mention where the default comes from
  doc: config: mention core.commentChar on commit.cleanup
  doc: notes: split out options with negations
  doc: notes: mention comment character configuration
  doc: notes: point out copy --stdin use with argv
  doc: notes: treat --stdin equally between copy/remove

 Documentation/config/commit.adoc  |  7 ++++---
 Documentation/git-notes.adoc      | 24 ++++++++++++++++++------
 Documentation/git-stripspace.adoc |  3 ++-
 3 files changed, 24 insertions(+), 10 deletions(-)


base-commit: cb96e1697ad6e54d11fc920c95f82977f8e438f8
-- 
2.49.0.780.g892193c3f50

[PATCH 1/6] doc: stripspace: mention where the default comes from

[kristofferhaugsbakk]

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

Also quote `#` in line with the modern formatting convention.

Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---

Notes (series):
    “modern formatting convention”
    
    It looks like characters are quoted with backticks in the commits I’ve
    seen by Jean-Noël Avila lately.

 Documentation/git-stripspace.adoc | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/Documentation/git-stripspace.adoc b/Documentation/git-stripspace.adoc
index a293327581a..1132a4cf9a9 100644
--- a/Documentation/git-stripspace.adoc
+++ b/Documentation/git-stripspace.adoc
@@ -37,7 +37,8 @@ OPTIONS
 -------
 -s::
 --strip-comments::
-	Skip and remove all lines starting with a comment character (default '#').
+	Skip and remove all lines starting with a comment character (default `#`).
+	See `core.commentChar` in linkgit:git-config[1].
 
 -c::
 --comment-lines::
-- 
2.49.0.780.g892193c3f50

[PATCH 2/6] doc: config: mention core.commentChar on commit.cleanup

[kristofferhaugsbakk]

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

Mention it in parentheses since we are in a configuration context.
Refer to the default as such, not as “the” character.

Also don’t mention `#` again; just say “comment character”.

Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---
 Documentation/config/commit.adoc | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/Documentation/config/commit.adoc b/Documentation/config/commit.adoc
index d3f4624fd27..208ae76c816 100644
--- a/Documentation/config/commit.adoc
+++ b/Documentation/config/commit.adoc
@@ -8,10 +8,11 @@ endif::git-commit[]
 	This setting overrides the default of the `--cleanup` option in
 	`git commit`. {see-git-commit} Changing the default can be useful
 	when you always want to keep lines that begin
-	with the comment character `#` in your log message, in which case you
+	with the comment character (`core.commentChar`, default `#`)
+	in your log message, in which case you
 	would do `git config commit.cleanup whitespace` (note that you will
-	have to remove the help lines that begin with `#` in the commit log
-	template yourself, if you do this).
+	have to remove the help lines that begin with the comment character
+	in the commit log template yourself, if you do this).
 
 `commit.gpgSign`::
 	A boolean to specify whether all commits should be GPG signed.
-- 
2.49.0.780.g892193c3f50

[PATCH 3/6] doc: notes: split out options with negations

[kristofferhaugsbakk]

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

Split these out so that they are easier to search for.[1]

[1]: https://lore.kernel.org/git/xmqqcyct1mtq.fsf@gitster.g/

Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---
 Documentation/git-notes.adoc | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/Documentation/git-notes.adoc b/Documentation/git-notes.adoc
index bcfe3dacd3f..8706b33f2ee 100644
--- a/Documentation/git-notes.adoc
+++ b/Documentation/git-notes.adoc
@@ -174,14 +174,16 @@ OPTIONS
 	Allow an empty note object to be stored. The default behavior is
 	to automatically remove empty notes.
 
-`--[no-]separator`::
 `--separator=<paragraph-break>`::
+`--separator`::
+`--no-separator`::
 	Specify a string used as a custom inter-paragraph separator
 	(a newline is added at the end as needed). If `--no-separator`, no
 	separators will be added between paragraphs.  Defaults to a blank
 	line.
 
-`--[no-]stripspace`::
+`--stripspace`::
+`--no-stripspace`::
 	Strip leading and trailing whitespace from the note message.
 	Also strip out empty lines other than a single line between
 	paragraphs. Lines starting with `#` will be stripped out
-- 
2.49.0.780.g892193c3f50

[PATCH 4/6] doc: notes: mention comment character configuration

[kristofferhaugsbakk]

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---
 Documentation/git-notes.adoc | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/Documentation/git-notes.adoc b/Documentation/git-notes.adoc
index 8706b33f2ee..1b714eb9e81 100644
--- a/Documentation/git-notes.adoc
+++ b/Documentation/git-notes.adoc
@@ -186,9 +186,12 @@ OPTIONS
 `--no-stripspace`::
 	Strip leading and trailing whitespace from the note message.
 	Also strip out empty lines other than a single line between
-	paragraphs. Lines starting with `#` will be stripped out
+	paragraphs. Lines starting with the comment character
+	(default `#`) will be stripped out
 	in non-editor cases like `-m`, `-F` and `-C`, but not in
 	editor case like `git notes edit`, `-c`, etc.
++
+See `core.commentChar` in linkgit:git-config[1].
 
 `--ref <ref>`::
 	Manipulate the notes tree in _<ref>_.  This overrides
-- 
2.49.0.780.g892193c3f50

[PATCH 5/6] doc: notes: point out copy --stdin use with argv

[kristofferhaugsbakk]

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

Unlike `remove --stdin`, this option cannot be combined with object
names given via the command line.

Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---
 Documentation/git-notes.adoc | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/Documentation/git-notes.adoc b/Documentation/git-notes.adoc
index 1b714eb9e81..d2d7dac8d41 100644
--- a/Documentation/git-notes.adoc
+++ b/Documentation/git-notes.adoc
@@ -87,6 +87,9 @@ In `--stdin` mode, take lines in the format
 on standard input, and copy the notes from each _<from-object>_ to its
 corresponding _<to-object>_.  (The optional _<rest>_ is ignored so that
 the command can read the input given to the `post-rewrite` hook.)
++
+`--stdin` cannot be combined with object names given on the command
+line.
 
 `append`::
 	Append new message(s) given by `-m` or `-F` options to an
-- 
2.49.0.780.g892193c3f50

[PATCH 6/6] doc: notes: treat --stdin equally between copy/remove

[kristofferhaugsbakk]

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

46538012d94 (notes remove: --stdin reads from the standard input,
2011-05-18) added `--stdin` for the `remove` subcommand, documenting it
in the “Options” section.  But `copy --stdin` was added before that, in
160baa0d9cb (notes: implement 'git notes copy --stdin', 2010-03-12).

Treat this option equally between the two subcommands:

• remove: mention `--stdin` on the subcommand as well, like for `copy`
• copy: mention it as well under the option documentation

Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---
 Documentation/git-notes.adoc | 10 +++++++---
 1 file changed, 7 insertions(+), 3 deletions(-)

diff --git a/Documentation/git-notes.adoc b/Documentation/git-notes.adoc
index d2d7dac8d41..1542850eaaa 100644
--- a/Documentation/git-notes.adoc
+++ b/Documentation/git-notes.adoc
@@ -127,6 +127,10 @@ When done, the user can either finalize the merge with
 	giving zero or one object from the command line, this is
 	equivalent to specifying an empty note message to
 	the `edit` subcommand.
++
+In `--stdin` mode, also remove the object names given on standard
+input. In other words, `--stdin` can be combined with object names from
+the command line.
 
 `prune`::
 	Remove all notes for non-existing/unreachable objects.
@@ -208,9 +212,9 @@ See `core.commentChar` in linkgit:git-config[1].
 	object that does not have notes attached to it.
 
 `--stdin`::
-	Also read the object names to remove notes from the standard
-	input (there is no reason you cannot combine this with object
-	names from the command line).
+	For `remove` and `copy`. See the respective subcommands. This
+	option can be combined with object names given via the command
+	line for `remove`. However, this is not the case for `copy`.
 
 `-n`::
 `--dry-run`::
-- 
2.49.0.780.g892193c3f50

Re: [PATCH 1/6] doc: stripspace: mention where the default comes from

[Junio C Hamano]

kristofferhaugsbakk@fastmail.com writes:

> From: Kristoffer Haugsbakk <code@khaugsbakk.name>
>
> Also quote `#` in line with the modern formatting convention.
>
> Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
> ---
>
> Notes (series):
>     “modern formatting convention”
>     
>     It looks like characters are quoted with backticks in the commits I’ve
>     seen by Jean-Noël Avila lately.
>
>  Documentation/git-stripspace.adoc | 3 ++-
>  1 file changed, 2 insertions(+), 1 deletion(-)
>
> diff --git a/Documentation/git-stripspace.adoc b/Documentation/git-stripspace.adoc
> index a293327581a..1132a4cf9a9 100644
> --- a/Documentation/git-stripspace.adoc
> +++ b/Documentation/git-stripspace.adoc
> @@ -37,7 +37,8 @@ OPTIONS
>  -------
>  -s::
>  --strip-comments::
> -	Skip and remove all lines starting with a comment character (default '#').
> +	Skip and remove all lines starting with a comment character (default `#`).
> +	See `core.commentChar` in linkgit:git-config[1].

I've seen this kind of thing treat the configuration as the first
level default, with the hardcoded value as a fallback, i.e. spelling
it more like this:

    ... a comment character.  Defaults to `core.commentChar`, which
    in turn defaults to `#`.

The way you phrased is syntactically easier to parse, but to some
readers, the readon why they are encouraged to learn about the
`core.commentChar` configuration may not be immediately obvious, so
I dunno.

Thanks.

Re: [PATCH 3/6] doc: notes: split out options with negations

[Junio C Hamano]

kristofferhaugsbakk@fastmail.com writes:

> -`--[no-]separator`::
>  `--separator=<paragraph-break>`::
> +`--separator`::
> +`--no-separator`::
>  	Specify a string used as a custom inter-paragraph separator
>  	(a newline is added at the end as needed). If `--no-separator`, no
>  	separators will be added between paragraphs.  Defaults to a blank
>  	line.

OK.

> -`--[no-]stripspace`::
> +`--stripspace`::
> +`--no-stripspace`::
>  	Strip leading and trailing whitespace from the note message.
>  	Also strip out empty lines other than a single line between
>  	paragraphs. Lines starting with `#` will be stripped out

Together with the post context lines, it is unclear what the default
behaviour is for the command.  It is not a new problem, but
hopefully the remaining 3 patches I haven't read would address it?

Let's keep reading.

Thanks.

Re: [PATCH 4/6] doc: notes: mention comment character configuration

[Junio C Hamano]

kristofferhaugsbakk@fastmail.com writes:

> From: Kristoffer Haugsbakk <code@khaugsbakk.name>
>
> Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
> ---
>  Documentation/git-notes.adoc | 5 ++++-
>  1 file changed, 4 insertions(+), 1 deletion(-)
>
> diff --git a/Documentation/git-notes.adoc b/Documentation/git-notes.adoc
> index 8706b33f2ee..1b714eb9e81 100644
> --- a/Documentation/git-notes.adoc
> +++ b/Documentation/git-notes.adoc
> @@ -186,9 +186,12 @@ OPTIONS
>  `--no-stripspace`::
>  	Strip leading and trailing whitespace from the note message.
>  	Also strip out empty lines other than a single line between
> -	paragraphs. Lines starting with `#` will be stripped out
> +	paragraphs. Lines starting with the comment character
> +	(default `#`) will be stripped out
>  	in non-editor cases like `-m`, `-F` and `-C`, but not in
>  	editor case like `git notes edit`, `-c`, etc.
> ++
> +See `core.commentChar` in linkgit:git-config[1].
>  
>  `--ref <ref>`::
>  	Manipulate the notes tree in _<ref>_.  This overrides

The above is more like [1/6] I commented on, rather than [2/6], so
the same comment "why is it suggested that I go read about that
variable?" applies.  Perhaps

    ... starting with the comment character (the `core.commentChar`
    configuration variable, if set, otherwise `#`) will be ...

or something?  I dunno.

Re: [PATCH 5/6] doc: notes: point out copy --stdin use with argv

[Junio C Hamano]

kristofferhaugsbakk@fastmail.com writes:

> From: Kristoffer Haugsbakk <code@khaugsbakk.name>
>
> Unlike `remove --stdin`, this option cannot be combined with object
> names given via the command line.
>
> Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
> ---
>  Documentation/git-notes.adoc | 3 +++
>  1 file changed, 3 insertions(+)

OK.

> diff --git a/Documentation/git-notes.adoc b/Documentation/git-notes.adoc
> index 1b714eb9e81..d2d7dac8d41 100644
> --- a/Documentation/git-notes.adoc
> +++ b/Documentation/git-notes.adoc
> @@ -87,6 +87,9 @@ In `--stdin` mode, take lines in the format
>  on standard input, and copy the notes from each _<from-object>_ to its
>  corresponding _<to-object>_.  (The optional _<rest>_ is ignored so that
>  the command can read the input given to the `post-rewrite` hook.)
> ++
> +`--stdin` cannot be combined with object names given on the command
> +line.
>  
>  `append`::
>  	Append new message(s) given by `-m` or `-F` options to an

Re: [PATCH 6/6] doc: notes: treat --stdin equally between copy/remove

[Junio C Hamano]

kristofferhaugsbakk@fastmail.com writes:

> From: Kristoffer Haugsbakk <code@khaugsbakk.name>
>
> 46538012d94 (notes remove: --stdin reads from the standard input,
> 2011-05-18) added `--stdin` for the `remove` subcommand, documenting it
> in the “Options” section.  But `copy --stdin` was added before that, in
> 160baa0d9cb (notes: implement 'git notes copy --stdin', 2010-03-12).
>
> Treat this option equally between the two subcommands:
>
> • remove: mention `--stdin` on the subcommand as well, like for `copy`
> • copy: mention it as well under the option documentation
>
> Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
> ---
>  Documentation/git-notes.adoc | 10 +++++++---
>  1 file changed, 7 insertions(+), 3 deletions(-)
>
> diff --git a/Documentation/git-notes.adoc b/Documentation/git-notes.adoc
> index d2d7dac8d41..1542850eaaa 100644
> --- a/Documentation/git-notes.adoc
> +++ b/Documentation/git-notes.adoc
> @@ -127,6 +127,10 @@ When done, the user can either finalize the merge with
>  	giving zero or one object from the command line, this is
>  	equivalent to specifying an empty note message to
>  	the `edit` subcommand.
> ++
> +In `--stdin` mode, also remove the object names given on standard
> +input. In other words, `--stdin` can be combined with object names from
> +the command line.
>  
>  `prune`::
>  	Remove all notes for non-existing/unreachable objects.
> @@ -208,9 +212,9 @@ See `core.commentChar` in linkgit:git-config[1].
>  	object that does not have notes attached to it.
>  
>  `--stdin`::
> -	Also read the object names to remove notes from the standard
> -	input (there is no reason you cannot combine this with object
> -	names from the command line).

The original was really bad, especially if it ignored the fact that
the 'copy' action also took the option.

> +	For `remove` and `copy`. See the respective subcommands. This
> +	option can be combined with object names given via the command
> +	line for `remove`. However, this is not the case for `copy`.

During my first read of this paragraph, I somehow read the first two
sentences as "if you want to learn how this option behaves with the
remove and copy subcommands, go read the documentation for these
subcommands", making me anticipate that the remainder of the
paragraph would talks about what happens when --stdin is given to
other subcommands.  Apparently that is not what is going on.

It may be simpler to just say

	Only valid for `remove` and `copy`.  See the respective
	subcommands.

and stop there.

Re: [PATCH 3/6] doc: notes: split out options with negations

[Junio C Hamano]

Junio C Hamano <gitster@pobox.com> writes:

> kristofferhaugsbakk@fastmail.com writes:
>
>> -`--[no-]separator`::
>>  `--separator=<paragraph-break>`::
>> +`--separator`::
>> +`--no-separator`::
>>  	Specify a string used as a custom inter-paragraph separator
>>  	(a newline is added at the end as needed). If `--no-separator`, no
>>  	separators will be added between paragraphs.  Defaults to a blank
>>  	line.
>
> OK.
>
>> -`--[no-]stripspace`::
>> +`--stripspace`::
>> +`--no-stripspace`::
>>  	Strip leading and trailing whitespace from the note message.
>>  	Also strip out empty lines other than a single line between
>>  	paragraphs. Lines starting with `#` will be stripped out
>
> Together with the post context lines, it is unclear what the default
> behaviour is for the command.  It is not a new problem, but
> hopefully the remaining 3 patches I haven't read would address it?

I guess this was left unresolved after the series, but it is
perfectly fine to leave it outside the topic.  Somebody else may
want to look into how exactly stripspace behaviour works by default
and how this option affects [*] and document it here.

[Footnote]

 * IIRC, we made the default to strip, unless the message came from
   an existing note in which case it is left intact; but whoever
   does the documentation update should check it.

Re: [PATCH 6/6] doc: notes: treat --stdin equally between copy/remove

[D. Ben Knoble]

On Tue, May 20, 2025 at 1:58 PM <kristofferhaugsbakk@fastmail.com> wrote:
>
> From: Kristoffer Haugsbakk <code@khaugsbakk.name>
>
> 46538012d94 (notes remove: --stdin reads from the standard input,
> 2011-05-18) added `--stdin` for the `remove` subcommand, documenting it
> in the “Options” section.  But `copy --stdin` was added before that, in
> 160baa0d9cb (notes: implement 'git notes copy --stdin', 2010-03-12).
>
> Treat this option equally between the two subcommands:
>
> • remove: mention `--stdin` on the subcommand as well, like for `copy`
> • copy: mention it as well under the option documentation

Ooh, bullet characters. I haven't seen anything quite like that in a
commit message in my short time watching the list. Neat!

-- 
D. Ben Knoble

Re: [PATCH 3/6] doc: notes: split out options with negations

[Kristoffer Haugsbakk]

On Wed, May 21, 2025, at 15:14, Junio C Hamano wrote:
>> Together with the post context lines, it is unclear what the default
>> behaviour is for the command.  It is not a new problem, but
>> hopefully the remaining 3 patches I haven't read would address it?
>
> I guess this was left unresolved after the series, but it is
> perfectly fine to leave it outside the topic.  Somebody else may
> want to look into how exactly stripspace behaviour works by default
> and how this option affects [*] and document it here.
>
> [Footnote]
>
>  * IIRC, we made the default to strip, unless the message came from
>    an existing note in which case it is left intact; but whoever
>    does the documentation update should check it.

Good point. I looked over the options for any ambiguity but missed this
one.

I’ll fix it on a separate patch in the next version.

-- 
Kristoffer

Re: [PATCH 6/6] doc: notes: treat --stdin equally between copy/remove

[Kristoffer Haugsbakk]

On Wed, May 21, 2025, at 15:19, D. Ben Knoble wrote:
> On Tue, May 20, 2025 at 1:58 PM <kristofferhaugsbakk@fastmail.com> wrote:
>> • remove: mention `--stdin` on the subcommand as well, like for `copy`
>> • copy: mention it as well under the option documentation
>
> Ooh, bullet characters. I haven't seen anything quite like that in a
> commit message in my short time watching the list. Neat!

They get through the reviews somehow. ;)

Re: [PATCH 6/6] doc: notes: treat --stdin equally between copy/remove

[Kristoffer Haugsbakk]

On Tue, May 20, 2025, at 21:19, Junio C Hamano wrote:
>> +	For `remove` and `copy`. See the respective subcommands. This
>> +	option can be combined with object names given via the command
>> +	line for `remove`. However, this is not the case for `copy`.
>
> During my first read of this paragraph, I somehow read the first two
> sentences as "if you want to learn how this option behaves with the
> remove and copy subcommands, go read the documentation for these
> subcommands", making me anticipate that the remainder of the
> paragraph would talks about what happens when --stdin is given to
> other subcommands.  Apparently that is not what is going on.
>
> It may be simpler to just say
>
> 	Only valid for `remove` and `copy`.  See the respective
> 	subcommands.
>
> and stop there.

Yep I agree.  Just leave it to the subcommand sections.

-- 
Kristoffer Haugsbakk

Re: [PATCH 1/6] doc: stripspace: mention where the default comes from

[Kristoffer Haugsbakk]

On Tue, May 20, 2025, at 21:06, Junio C Hamano wrote:
>> diff --git a/Documentation/git-stripspace.adoc b/Documentation/git-stripspace.adoc
>> index a293327581a..1132a4cf9a9 100644
>> --- a/Documentation/git-stripspace.adoc
>> +++ b/Documentation/git-stripspace.adoc
>> @@ -37,7 +37,8 @@ OPTIONS
>>  -------
>>  -s::
>>  --strip-comments::
>> -	Skip and remove all lines starting with a comment character (default '#').
>> +	Skip and remove all lines starting with a comment character (default `#`).
>> +	See `core.commentChar` in linkgit:git-config[1].
>
> I've seen this kind of thing treat the configuration as the first
> level default, with the hardcoded value as a fallback, i.e. spelling
> it more like this:
>
>     ... a comment character.  Defaults to `core.commentChar`, which
>     in turn defaults to `#`.
>
> The way you phrased is syntactically easier to parse, but to some
> readers, the readon why they are encouraged to learn about the
> `core.commentChar` configuration may not be immediately obvious, so
> I dunno.
>
> Thanks.

I’m fine with that too.  I ended up with this version because I tried to
avoid complex sentences.  But it’s best to avoid a new paragraph.

Another alternative:

    a comment character (`core.commentChar`, default `#`)

And the linkgit to git-config(1) is probably not needed on this kind
of doc.

-- 
Kristoffer

Re: [PATCH 3/6] doc: notes: split out options with negations

[Junio C Hamano]

"Kristoffer Haugsbakk" <code@khaugsbakk.name> writes:

>> I guess this was left unresolved after the series, but it is
>> perfectly fine to leave it outside the topic.  Somebody else may
>> want to look into how exactly stripspace behaviour works by default
>> and how this option affects [*] and document it here.
>>
>> [Footnote]
>>
>>  * IIRC, we made the default to strip, unless the message came from
>>    an existing note in which case it is left intact; but whoever
>>    does the documentation update should check it.
>
> Good point. I looked over the options for any ambiguity but missed this
> one.

Heh, that was one of the things the article you cited stressed on [*].

> I’ll fix it on a separate patch in the next version.

Thanks.


[Reference]

* https://lore.kernel.org/git/xmqqcyct1mtq.fsf@gitster.g/

Re: [PATCH 6/6] doc: notes: treat --stdin equally between copy/remove

[Junio C Hamano]

"Kristoffer Haugsbakk" <code@khaugsbakk.name> writes:

> On Wed, May 21, 2025, at 15:19, D. Ben Knoble wrote:
>> On Tue, May 20, 2025 at 1:58 PM <kristofferhaugsbakk@fastmail.com> wrote:
>>> • remove: mention `--stdin` on the subcommand as well, like for `copy`
>>> • copy: mention it as well under the option documentation
>>
>> Ooh, bullet characters. I haven't seen anything quite like that in a
>> commit message in my short time watching the list. Neat!
>
> They get through the reviews somehow. ;)

The "downside" may be that they may inconvenience folks still living
in ASCII-only world, but I suspect it is rather hard to find
ASCII-only terminals that render not-so-uncommon Unicode characters
as garbage, so perhaps there is no longer any such downside?

Re: [PATCH 3/6] doc: notes: split out options with negations

[Kristoffer Haugsbakk]

On Wed, May 21, 2025, at 17:47, Junio C Hamano wrote:
> Heh, that was one of the things the article you cited stressed on [*].

I promise that part was fresh in my mind at that point. But apparently 
the mind itself was not that fresh.

-- 
Kristoffer

[PATCH v2 0/9] doc: --stdin on notes and core.commentChar mentions

[kristofferhaugsbakk]

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

I wanted to fix `--stdin` in the git-notes(1) documentation.  Then I
found some other things on that doc as well as things to do with
`core.commentChar`.

§ Changes v2

Address the feedback on v1.

I discovered that patch “doc: notes: mention comment character
configuration” was misguided since

1. Mentioning the comment character isn’t really relevant anywhere
2. The text conflates `--[no-]stripspace` with handling comment lines,
   which is wrong

That patch is replaced with patches 4 and 5.

See the notes on the patches for details.

Kristoffer Haugsbakk (9):
  doc: stripspace: mention where the default comes from
  doc: config: mention core.commentChar on commit.cleanup
  doc: notes: split out options with negated forms
  doc: notes: rework --[no-]stripspace
  doc: notes: remove stripspace discussion from other options
  doc: notes: clearly state that --stripspace is the default
  doc: notes: point out copy --stdin use with argv
  doc: notes: treat --stdin equally between copy/remove
  doc: notes: use stuck form throughout

 Documentation/config/commit.adoc  |  7 +++--
 Documentation/git-notes.adoc      | 51 ++++++++++++++++++-------------
 Documentation/git-stripspace.adoc |  3 +-
 3 files changed, 36 insertions(+), 25 deletions(-)

Interdiff against v1:
diff --git a/Documentation/git-notes.adoc b/Documentation/git-notes.adoc
index 1542850eaaa..43436daeccc 100644
--- a/Documentation/git-notes.adoc
+++ b/Documentation/git-notes.adoc
@@ -151,26 +151,18 @@ OPTIONS
 	Use the given note message (instead of prompting).
 	If multiple `-m` options are given, their values
 	are concatenated as separate paragraphs.
-	Lines starting with `#` and empty lines other than a
-	single line between paragraphs will be stripped out.
-	If you wish to keep them verbatim, use `--no-stripspace`.
 
 `-F <file>`::
 `--file=<file>`::
 	Take the note message from the given file.  Use `-` to
 	read the note message from the standard input.
-	Lines starting with `#` and empty lines other than a
-	single line between paragraphs will be stripped out.
-	If you wish to keep them verbatim, use `--no-stripspace`.
 
 `-C <object>`::
 `--reuse-message=<object>`::
 	Take the given blob object (for example, another note) as the
 	note message. (Use `git notes copy <object>` instead to
-	copy notes between objects.).  By default, message will be
-	copied verbatim, but if you wish to strip out the lines
-	starting with `#` and empty lines other than a single line
-	between paragraphs, use with `--stripspace` option.
+	copy notes between objects.)  Implies `--no-stripspace` since
+	the default behavior is to copy the message verbatim.
 
 `-c <object>`::
 `--reedit-message=<object>`::
@@ -191,16 +183,23 @@ OPTIONS
 
 `--stripspace`::
 `--no-stripspace`::
-	Strip leading and trailing whitespace from the note message.
-	Also strip out empty lines other than a single line between
-	paragraphs. Lines starting with the comment character
-	(default `#`) will be stripped out
-	in non-editor cases like `-m`, `-F` and `-C`, but not in
-	editor case like `git notes edit`, `-c`, etc.
+	Clean up whitespace. Specifically (see
+	linkgit:git-stripspace[1]):
 +
-See `core.commentChar` in linkgit:git-config[1].
+--
+- remove trailing whitespace from all lines
+- collapse multiple consecutive empty lines into one empty line
+- remove empty lines from the beginning and end of the input
+- add a missing `\n` to the last line if necessary.
+--
++
+`--stripspace` is the default except for
+`-C`/`--reuse-message`. However, keep in mind that this depends on the
+order of similar options. For example, for `-C <object> -m<message>`,
+`--stripspace` will be used because the default for `-m` overrides the
+previous `-C`.
 
-`--ref <ref>`::
+`--ref=<ref>`::
 	Manipulate the notes tree in _<ref>_.  This overrides
 	`GIT_NOTES_REF` and the `core.notesRef` configuration.  The ref
 	specifies the full refname when it begins with `refs/notes/`; when it
@@ -212,9 +211,7 @@ See `core.commentChar` in linkgit:git-config[1].
 	object that does not have notes attached to it.
 
 `--stdin`::
-	For `remove` and `copy`. See the respective subcommands. This
-	option can be combined with object names given via the command
-	line for `remove`. However, this is not the case for `copy`.
+	For `remove` and `copy`. See the respective subcommands.
 
 `-n`::
 `--dry-run`::
diff --git a/Documentation/git-stripspace.adoc b/Documentation/git-stripspace.adoc
index 1132a4cf9a9..37287f211f0 100644
--- a/Documentation/git-stripspace.adoc
+++ b/Documentation/git-stripspace.adoc
@@ -37,8 +37,8 @@ OPTIONS
 -------
 -s::
 --strip-comments::
-	Skip and remove all lines starting with a comment character (default `#`).
-	See `core.commentChar` in linkgit:git-config[1].
+	Skip and remove all lines starting with a comment character
+	(`core.commentChar`, default `#`).
 
 -c::
 --comment-lines::
Range-diff against v1:
 -:  ----------- >  1:  bf3ea7f23c0 doc: stripspace: mention where the default comes from
 2:  b43b78aba63 =  2:  e9cf956a824 doc: config: mention core.commentChar on commit.cleanup
 3:  d2b6864b707 !  3:  14dc58120e3 doc: notes: split out options with negations
    @@ Metadata
     Author: Kristoffer Haugsbakk <code@khaugsbakk.name>
     
      ## Commit message ##
    -    doc: notes: split out options with negations
    +    doc: notes: split out options with negated forms
     
         Split these out so that they are easier to search for.[1]
     
    @@ Commit message
     
         Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
     
    +
    + ## Notes (series) ##
    +    v2:
    +    • Message: Use “negated form” since that seems more typical
    +
      ## Documentation/git-notes.adoc ##
     @@ Documentation/git-notes.adoc: OPTIONS
      	Allow an empty note object to be stored. The default behavior is
 4:  f3f54a3537f !  4:  c68a91f81ba doc: notes: mention comment character configuration
    @@ Metadata
     Author: Kristoffer Haugsbakk <code@khaugsbakk.name>
     
      ## Commit message ##
    -    doc: notes: mention comment character configuration
    +    doc: notes: rework --[no-]stripspace
    +
    +    Document this option by copying the bullet list from git-stripspace(1).
    +    A bullet list is cleaner when there are this many points to consider.
    +    We also get a more standardized description of the multiple-blank-lines
    +    behavior.  Compare the repeating (git-notes(1)):
    +
    +        empty lines other than a single line between paragraphs
    +
    +    With (git-stripspace(1)):
    +
    +        multiple consecutive empty lines
    +
    +    And:
    +
    +        leading [...] whitespace
    +
    +    With:
    +
    +        empty lines from the beginning
    +
    +    Leading whitespace in the form of spaces (indentation) are not removed.
    +    However, empty lines at the start of the message are removed.
    +
    +    Note that we drop the mentions of comment line handling because they are
    +    wrong; this option does not control how lines which can be recognized as
    +    comment lines are handled.  Only interactivity controls that:
    +
    +    • Comment lines are stripped after editing interactively
    +    • Lines which could be recognized as comment lines are left alone when
    +      the message is given non-interactively
    +
    +    So it is misleading to document the comment line behavior on
    +    this option.
    +
    +    Further, the text is wrong:
    +
    +        Lines starting with `#` will be stripped out in non-editor cases
    +        like `-m`, [...]
    +
    +    Comment lines are still indirectly discussed on other options.  We will
    +    deal with them in the next commit.
     
         Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
     
    +
    + ## Notes (series) ##
    +    v2:
    +    • New
    +    • Together with one other other patch replaces v1 patch “doc: notes:
    +      mention comment character configuration”
    +    • I figured out that mentioning the comment character/comment lines
    +      doesn’t make sense here.  So all attempts to rephrase “comment
    +      character” or “lines that start with `#`” are gone
    +
      ## Documentation/git-notes.adoc ##
     @@ Documentation/git-notes.adoc: OPTIONS
    + 
    + `--stripspace`::
      `--no-stripspace`::
    - 	Strip leading and trailing whitespace from the note message.
    - 	Also strip out empty lines other than a single line between
    +-	Strip leading and trailing whitespace from the note message.
    +-	Also strip out empty lines other than a single line between
     -	paragraphs. Lines starting with `#` will be stripped out
    -+	paragraphs. Lines starting with the comment character
    -+	(default `#`) will be stripped out
    - 	in non-editor cases like `-m`, `-F` and `-C`, but not in
    - 	editor case like `git notes edit`, `-c`, etc.
    +-	in non-editor cases like `-m`, `-F` and `-C`, but not in
    +-	editor case like `git notes edit`, `-c`, etc.
    ++	Clean up whitespace. Specifically (see
    ++	linkgit:git-stripspace[1]):
     ++
    -+See `core.commentChar` in linkgit:git-config[1].
    ++- remove trailing whitespace from all lines
    ++- collapse multiple consecutive empty lines into one empty line
    ++- remove empty lines from the beginning and end of the input
    ++- add a missing `\n` to the last line if necessary.
      
      `--ref <ref>`::
      	Manipulate the notes tree in _<ref>_.  This overrides
 1:  630ef019786 !  5:  f4755040f38 doc: stripspace: mention where the default comes from
    @@ Metadata
     Author: Kristoffer Haugsbakk <code@khaugsbakk.name>
     
      ## Commit message ##
    -    doc: stripspace: mention where the default comes from
    +    doc: notes: remove stripspace discussion from other options
     
    -    Also quote `#` in line with the modern formatting convention.
    +    Cleaning up whitespace in metadata is typical porcelain behavior and
    +    this default does not need to be pointed out.[1]  Only speak up when
    +    the default `--stripspace` is not used.
    +
    +    Also remove all misleading mentions of comment lines in the process;
    +    see the previous commit.
    +
    +    Also remove the period that trails the parenthetical here.
    +
    +    † 1: See `-F` in git-commit(1) which has nothing to say about whitespace
    +        cleanup.  The cleanup discussion is on `--cleanup`.
     
         Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
     
     
      ## Notes (series) ##
    -    “modern formatting convention”
    -
    -    It looks like characters are quoted with backticks in the commits I’ve
    -    seen by Jean-Noël Avila lately.
    -
    - ## Documentation/git-stripspace.adoc ##
    -@@ Documentation/git-stripspace.adoc: OPTIONS
    - -------
    - -s::
    - --strip-comments::
    --	Skip and remove all lines starting with a comment character (default '#').
    -+	Skip and remove all lines starting with a comment character (default `#`).
    -+	See `core.commentChar` in linkgit:git-config[1].
    +    v2:
    +    • New
    +    • Together with one other patch replaces v1 patch “doc: notes:
    +      mention comment character configuration”
    +    • I figured out that mentioning the comment character/comment lines
    +      doesn’t make sense here.  So all attempts to rephrase “comment
    +      character” or “lines that start with `#`” are gone
    +
    + ## Documentation/git-notes.adoc ##
    +@@ Documentation/git-notes.adoc: OPTIONS
    + 	Use the given note message (instead of prompting).
    + 	If multiple `-m` options are given, their values
    + 	are concatenated as separate paragraphs.
    +-	Lines starting with `#` and empty lines other than a
    +-	single line between paragraphs will be stripped out.
    +-	If you wish to keep them verbatim, use `--no-stripspace`.
    + 
    + `-F <file>`::
    + `--file=<file>`::
    + 	Take the note message from the given file.  Use `-` to
    + 	read the note message from the standard input.
    +-	Lines starting with `#` and empty lines other than a
    +-	single line between paragraphs will be stripped out.
    +-	If you wish to keep them verbatim, use `--no-stripspace`.
    + 
    + `-C <object>`::
    + `--reuse-message=<object>`::
    + 	Take the given blob object (for example, another note) as the
    + 	note message. (Use `git notes copy <object>` instead to
    +-	copy notes between objects.).  By default, message will be
    +-	copied verbatim, but if you wish to strip out the lines
    +-	starting with `#` and empty lines other than a single line
    +-	between paragraphs, use with `--stripspace` option.
    ++	copy notes between objects.)  Implies `--no-stripspace` since
    ++	the default behavior is to copy the message verbatim.
      
    - -c::
    - --comment-lines::
    + `-c <object>`::
    + `--reedit-message=<object>`::
 -:  ----------- >  6:  be89c3349d2 doc: notes: clearly state that --stripspace is the default
 5:  cbb177479ca =  7:  d8a22847a7d doc: notes: point out copy --stdin use with argv
 6:  68e5eb78040 !  8:  3e8ecf1b668 doc: notes: treat --stdin equally between copy/remove
    @@ Commit message
     
         Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
     
    +
    + ## Notes (series) ##
    +    v2:
    +    • On --stdin: just refer to the respective subcommands and stop there.
    +      As suggested.
    +
    +      Link: https://lore.kernel.org/git/xmqq34czhyz8.fsf@gitster.g/
    +
      ## Documentation/git-notes.adoc ##
     @@ Documentation/git-notes.adoc: When done, the user can either finalize the merge with
      	giving zero or one object from the command line, this is
    @@ Documentation/git-notes.adoc: When done, the user can either finalize the merge
      
      `prune`::
      	Remove all notes for non-existing/unreachable objects.
    -@@ Documentation/git-notes.adoc: See `core.commentChar` in linkgit:git-config[1].
    +@@ Documentation/git-notes.adoc: previous `-C`.
      	object that does not have notes attached to it.
      
      `--stdin`::
     -	Also read the object names to remove notes from the standard
     -	input (there is no reason you cannot combine this with object
     -	names from the command line).
    -+	For `remove` and `copy`. See the respective subcommands. This
    -+	option can be combined with object names given via the command
    -+	line for `remove`. However, this is not the case for `copy`.
    ++	For `remove` and `copy`. See the respective subcommands.
      
      `-n`::
      `--dry-run`::
 -:  ----------- >  9:  73bdcaecae5 doc: notes: use stuck form throughout

base-commit: cb96e1697ad6e54d11fc920c95f82977f8e438f8
-- 
2.49.0.780.g892193c3f50

[PATCH v2 1/9] doc: stripspace: mention where the default comes from

[kristofferhaugsbakk]

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

Also quote `#` in line with the modern formatting convention.

Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---

Notes (series):
    v2:
    • More terse mention of the default as well as the configuration
      variable.  Don’t link to git-config(1), there’s no real need.
    
      Link: https://lore.kernel.org/git/xmqqjz6bhzkm.fsf@gitster.g/
    v1:
    • “modern formatting convention”
    
      It looks like characters are quoted with backticks in the commits I’ve
      seen by Jean-Noël Avila lately.

 Documentation/git-stripspace.adoc | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/Documentation/git-stripspace.adoc b/Documentation/git-stripspace.adoc
index a293327581a..37287f211f0 100644
--- a/Documentation/git-stripspace.adoc
+++ b/Documentation/git-stripspace.adoc
@@ -37,7 +37,8 @@ OPTIONS
 -------
 -s::
 --strip-comments::
-	Skip and remove all lines starting with a comment character (default '#').
+	Skip and remove all lines starting with a comment character
+	(`core.commentChar`, default `#`).
 
 -c::
 --comment-lines::
-- 
2.49.0.780.g892193c3f50

[PATCH v2 2/9] doc: config: mention core.commentChar on commit.cleanup

[kristofferhaugsbakk]

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

Mention it in parentheses since we are in a configuration context.
Refer to the default as such, not as “the” character.

Also don’t mention `#` again; just say “comment character”.

Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---
 Documentation/config/commit.adoc | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/Documentation/config/commit.adoc b/Documentation/config/commit.adoc
index d3f4624fd27..208ae76c816 100644
--- a/Documentation/config/commit.adoc
+++ b/Documentation/config/commit.adoc
@@ -8,10 +8,11 @@ endif::git-commit[]
 	This setting overrides the default of the `--cleanup` option in
 	`git commit`. {see-git-commit} Changing the default can be useful
 	when you always want to keep lines that begin
-	with the comment character `#` in your log message, in which case you
+	with the comment character (`core.commentChar`, default `#`)
+	in your log message, in which case you
 	would do `git config commit.cleanup whitespace` (note that you will
-	have to remove the help lines that begin with `#` in the commit log
-	template yourself, if you do this).
+	have to remove the help lines that begin with the comment character
+	in the commit log template yourself, if you do this).
 
 `commit.gpgSign`::
 	A boolean to specify whether all commits should be GPG signed.
-- 
2.49.0.780.g892193c3f50

[PATCH v2 3/9] doc: notes: split out options with negated forms

[kristofferhaugsbakk]

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

Split these out so that they are easier to search for.[1]

[1]: https://lore.kernel.org/git/xmqqcyct1mtq.fsf@gitster.g/

Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---

Notes (series):
    v2:
    • Message: Use “negated form” since that seems more typical

 Documentation/git-notes.adoc | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/Documentation/git-notes.adoc b/Documentation/git-notes.adoc
index bcfe3dacd3f..8706b33f2ee 100644
--- a/Documentation/git-notes.adoc
+++ b/Documentation/git-notes.adoc
@@ -174,14 +174,16 @@ OPTIONS
 	Allow an empty note object to be stored. The default behavior is
 	to automatically remove empty notes.
 
-`--[no-]separator`::
 `--separator=<paragraph-break>`::
+`--separator`::
+`--no-separator`::
 	Specify a string used as a custom inter-paragraph separator
 	(a newline is added at the end as needed). If `--no-separator`, no
 	separators will be added between paragraphs.  Defaults to a blank
 	line.
 
-`--[no-]stripspace`::
+`--stripspace`::
+`--no-stripspace`::
 	Strip leading and trailing whitespace from the note message.
 	Also strip out empty lines other than a single line between
 	paragraphs. Lines starting with `#` will be stripped out
-- 
2.49.0.780.g892193c3f50

[PATCH v2 4/9] doc: notes: rework --[no-]stripspace

[kristofferhaugsbakk]

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

Document this option by copying the bullet list from git-stripspace(1).
A bullet list is cleaner when there are this many points to consider.
We also get a more standardized description of the multiple-blank-lines
behavior.  Compare the repeating (git-notes(1)):

    empty lines other than a single line between paragraphs

With (git-stripspace(1)):

    multiple consecutive empty lines

And:

    leading [...] whitespace

With:

    empty lines from the beginning

Leading whitespace in the form of spaces (indentation) are not removed.
However, empty lines at the start of the message are removed.

Note that we drop the mentions of comment line handling because they are
wrong; this option does not control how lines which can be recognized as
comment lines are handled.  Only interactivity controls that:

• Comment lines are stripped after editing interactively
• Lines which could be recognized as comment lines are left alone when
  the message is given non-interactively

So it is misleading to document the comment line behavior on
this option.

Further, the text is wrong:

    Lines starting with `#` will be stripped out in non-editor cases
    like `-m`, [...]

Comment lines are still indirectly discussed on other options.  We will
deal with them in the next commit.

Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---

Notes (series):
    v2:
    • New
    • Together with one other other patch replaces v1 patch “doc: notes:
      mention comment character configuration”
    • I figured out that mentioning the comment character/comment lines
      doesn’t make sense here.  So all attempts to rephrase “comment
      character” or “lines that start with `#`” are gone

 Documentation/git-notes.adoc | 12 +++++++-----
 1 file changed, 7 insertions(+), 5 deletions(-)

diff --git a/Documentation/git-notes.adoc b/Documentation/git-notes.adoc
index 8706b33f2ee..d672794a942 100644
--- a/Documentation/git-notes.adoc
+++ b/Documentation/git-notes.adoc
@@ -184,11 +184,13 @@ OPTIONS
 
 `--stripspace`::
 `--no-stripspace`::
-	Strip leading and trailing whitespace from the note message.
-	Also strip out empty lines other than a single line between
-	paragraphs. Lines starting with `#` will be stripped out
-	in non-editor cases like `-m`, `-F` and `-C`, but not in
-	editor case like `git notes edit`, `-c`, etc.
+	Clean up whitespace. Specifically (see
+	linkgit:git-stripspace[1]):
++
+- remove trailing whitespace from all lines
+- collapse multiple consecutive empty lines into one empty line
+- remove empty lines from the beginning and end of the input
+- add a missing `\n` to the last line if necessary.
 
 `--ref <ref>`::
 	Manipulate the notes tree in _<ref>_.  This overrides
-- 
2.49.0.780.g892193c3f50

[PATCH v2 5/9] doc: notes: remove stripspace discussion from other options

[kristofferhaugsbakk]

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

Cleaning up whitespace in metadata is typical porcelain behavior and
this default does not need to be pointed out.[1]  Only speak up when
the default `--stripspace` is not used.

Also remove all misleading mentions of comment lines in the process;
see the previous commit.

Also remove the period that trails the parenthetical here.

† 1: See `-F` in git-commit(1) which has nothing to say about whitespace
    cleanup.  The cleanup discussion is on `--cleanup`.

Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---

Notes (series):
    v2:
    • New
    • Together with one other patch replaces v1 patch “doc: notes:
      mention comment character configuration”
    • I figured out that mentioning the comment character/comment lines
      doesn’t make sense here.  So all attempts to rephrase “comment
      character” or “lines that start with `#`” are gone

 Documentation/git-notes.adoc | 12 ++----------
 1 file changed, 2 insertions(+), 10 deletions(-)

diff --git a/Documentation/git-notes.adoc b/Documentation/git-notes.adoc
index d672794a942..383e8bca685 100644
--- a/Documentation/git-notes.adoc
+++ b/Documentation/git-notes.adoc
@@ -144,26 +144,18 @@ OPTIONS
 	Use the given note message (instead of prompting).
 	If multiple `-m` options are given, their values
 	are concatenated as separate paragraphs.
-	Lines starting with `#` and empty lines other than a
-	single line between paragraphs will be stripped out.
-	If you wish to keep them verbatim, use `--no-stripspace`.
 
 `-F <file>`::
 `--file=<file>`::
 	Take the note message from the given file.  Use `-` to
 	read the note message from the standard input.
-	Lines starting with `#` and empty lines other than a
-	single line between paragraphs will be stripped out.
-	If you wish to keep them verbatim, use `--no-stripspace`.
 
 `-C <object>`::
 `--reuse-message=<object>`::
 	Take the given blob object (for example, another note) as the
 	note message. (Use `git notes copy <object>` instead to
-	copy notes between objects.).  By default, message will be
-	copied verbatim, but if you wish to strip out the lines
-	starting with `#` and empty lines other than a single line
-	between paragraphs, use with `--stripspace` option.
+	copy notes between objects.)  Implies `--no-stripspace` since
+	the default behavior is to copy the message verbatim.
 
 `-c <object>`::
 `--reedit-message=<object>`::
-- 
2.49.0.780.g892193c3f50

[PATCH v2 6/9] doc: notes: clearly state that --stripspace is the default

[kristofferhaugsbakk]

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

Clearly state when which of the regular and negated form of the
option take effect.[1]

[1]: https://lore.kernel.org/git/xmqqcyct1mtq.fsf@gitster.g/

Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---

Notes (series):
    v2:
    • New
    • The `--` are to prevent the new paragraph from becoming a continuation
      of the last bullet point
    • Junio pointed out that I didn’t go over the part about checking
      which variant (regular or negation) are the default.  See the link:
    
      https://lore.kernel.org/git/xmqqcyct1mtq.fsf@gitster.g/
    
      I decided to do this on this series.
    
      Link: https://lore.kernel.org/git/xmqqfrgzhzbp.fsf@gitster.g/
    • The last part of the paragraph is based on the commit message of
      c4e2aa7d45f (notes.c: introduce "--[no-]stripspace" option,
      2023-05-27).
    
      See the review on the patch:
    
         https://lore.kernel.org/git/xmqq4jp326oj.fsf@gitster.g/
    
      There was concern about the order of options:
    
          >     ... One more thing need to note is "the order of
          >     the options matter", [...]
    
          This sounds more like a design/implementation mistake that we may
          want to fix.
    
      This new part is supposed to address that.

 Documentation/git-notes.adoc | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/Documentation/git-notes.adoc b/Documentation/git-notes.adoc
index 383e8bca685..bad83116329 100644
--- a/Documentation/git-notes.adoc
+++ b/Documentation/git-notes.adoc
@@ -179,10 +179,18 @@ OPTIONS
 	Clean up whitespace. Specifically (see
 	linkgit:git-stripspace[1]):
 +
+--
 - remove trailing whitespace from all lines
 - collapse multiple consecutive empty lines into one empty line
 - remove empty lines from the beginning and end of the input
 - add a missing `\n` to the last line if necessary.
+--
++
+`--stripspace` is the default except for
+`-C`/`--reuse-message`. However, keep in mind that this depends on the
+order of similar options. For example, for `-C <object> -m<message>`,
+`--stripspace` will be used because the default for `-m` overrides the
+previous `-C`.
 
 `--ref <ref>`::
 	Manipulate the notes tree in _<ref>_.  This overrides
-- 
2.49.0.780.g892193c3f50

[PATCH v2 7/9] doc: notes: point out copy --stdin use with argv

[kristofferhaugsbakk]

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

Unlike `remove --stdin`, this option cannot be combined with object
names given via the command line.

Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---
 Documentation/git-notes.adoc | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/Documentation/git-notes.adoc b/Documentation/git-notes.adoc
index bad83116329..ad152aa94ce 100644
--- a/Documentation/git-notes.adoc
+++ b/Documentation/git-notes.adoc
@@ -87,6 +87,9 @@ In `--stdin` mode, take lines in the format
 on standard input, and copy the notes from each _<from-object>_ to its
 corresponding _<to-object>_.  (The optional _<rest>_ is ignored so that
 the command can read the input given to the `post-rewrite` hook.)
++
+`--stdin` cannot be combined with object names given on the command
+line.
 
 `append`::
 	Append new message(s) given by `-m` or `-F` options to an
-- 
2.49.0.780.g892193c3f50

[PATCH v2 8/9] doc: notes: treat --stdin equally between copy/remove

[kristofferhaugsbakk]

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

46538012d94 (notes remove: --stdin reads from the standard input,
2011-05-18) added `--stdin` for the `remove` subcommand, documenting it
in the “Options” section.  But `copy --stdin` was added before that, in
160baa0d9cb (notes: implement 'git notes copy --stdin', 2010-03-12).

Treat this option equally between the two subcommands:

• remove: mention `--stdin` on the subcommand as well, like for `copy`
• copy: mention it as well under the option documentation

Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---

Notes (series):
    v2:
    • On --stdin: just refer to the respective subcommands and stop there.
      As suggested.
    
      Link: https://lore.kernel.org/git/xmqq34czhyz8.fsf@gitster.g/

 Documentation/git-notes.adoc | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/Documentation/git-notes.adoc b/Documentation/git-notes.adoc
index ad152aa94ce..a0167af5aba 100644
--- a/Documentation/git-notes.adoc
+++ b/Documentation/git-notes.adoc
@@ -127,6 +127,10 @@ When done, the user can either finalize the merge with
 	giving zero or one object from the command line, this is
 	equivalent to specifying an empty note message to
 	the `edit` subcommand.
++
+In `--stdin` mode, also remove the object names given on standard
+input. In other words, `--stdin` can be combined with object names from
+the command line.
 
 `prune`::
 	Remove all notes for non-existing/unreachable objects.
@@ -207,9 +211,7 @@ previous `-C`.
 	object that does not have notes attached to it.
 
 `--stdin`::
-	Also read the object names to remove notes from the standard
-	input (there is no reason you cannot combine this with object
-	names from the command line).
+	For `remove` and `copy`. See the respective subcommands.
 
 `-n`::
 `--dry-run`::
-- 
2.49.0.780.g892193c3f50

[PATCH v2 9/9] doc: notes: use stuck form throughout

[kristofferhaugsbakk]

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

gitcli(7) recommends the *stuck form*.  `--ref` is the only one which
does not use it.

Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---

Notes (series):
    v2:
    • New
    • I didn’t spot this in the first round.  Hopefully it’s fine to include
      it as well while we are editing this file.  I would consider making a
      separate thread if I wasn’t editing nearby hunks.

 Documentation/git-notes.adoc | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/git-notes.adoc b/Documentation/git-notes.adoc
index a0167af5aba..43436daeccc 100644
--- a/Documentation/git-notes.adoc
+++ b/Documentation/git-notes.adoc
@@ -199,7 +199,7 @@ order of similar options. For example, for `-C <object> -m<message>`,
 `--stripspace` will be used because the default for `-m` overrides the
 previous `-C`.
 
-`--ref <ref>`::
+`--ref=<ref>`::
 	Manipulate the notes tree in _<ref>_.  This overrides
 	`GIT_NOTES_REF` and the `core.notesRef` configuration.  The ref
 	specifies the full refname when it begins with `refs/notes/`; when it
-- 
2.49.0.780.g892193c3f50

Re: [PATCH v2 6/9] doc: notes: clearly state that --stripspace is the default

[Junio C Hamano]

kristofferhaugsbakk@fastmail.com writes:

>       See the review on the patch:
>     
>          https://lore.kernel.org/git/xmqq4jp326oj.fsf@gitster.g/
>     
>       There was concern about the order of options:
>     
>           >     ... One more thing need to note is "the order of
>           >     the options matter", [...]
>     
>           This sounds more like a design/implementation mistake that we may
>           want to fix.

That is a comment on the 8th iteration of the series, which is
different from what you are documenting, which is 11th if I am
reading the thread correctly.

Comparing [v8 6/6] with [v11 6/7],

https://lore.kernel.org/git/f60f743203d78a489b90df81472e71391b45367d.1682429602.git.dyroneteng@gmail.com/
https://lore.kernel.org/git/19865941bb29c28a690ed3e28fc4f6870e352923.1685174012.git.dyroneteng@gmail.com/

I notice that the later version has .stripspace member in note_msg
as well as note_data.  note_data has a collection of multiple
note_msg instances.  Each of note_msg comes from various sources,
like '-m', '-C', etc., and each of these types have hardcoded
default values for note_msg.stripspace (mostly to strip but note_msg
that comes from an existing note blob has stripspace unset).  When
concat_messages() takes note_msg instances in a note_data together,
it _could_ do:

 - if note_data.stripspace is explicitly specified, use that,
   otherwise use note_msg.stripspace, to cleanse the message
   contained in note_msg.

and concatenate the results.  But even at v11 of the series, the
implementation of concat_messages() uses the stripspace determined
to instead cleanse the concatenated result.

Which I think is simply buggy.

What it should do probably is

 - Loop over d->messages[] and:
   - if d->stripspace is set or d->messages[]->stripspace is set,
     cleanse the message (i.e. d->messages[]->buf) and append to d->buf
   - otherwise append d->messages[]->buf as-is to d->buf

 - If d->stripspace is set, cleanse d->buf (may not be necessary, as
   the messages that are concatenated have _all_ lost leading and
   trailing blank lines before concatenation).

and that would truly fix the problem pointed out during the review
of v8.

> +--
> ++
> +`--stripspace` is the default except for
> +`-C`/`--reuse-message`. However, keep in mind that this depends on the
> +order of similar options. For example, for `-C <object> -m<message>`,
> +`--stripspace` will be used because the default for `-m` overrides the
> +previous `-C`.

So, I think this is an accurate description of the current
behaviour, but we might want to phrase the part that comes after
"however" as documenting a known bug, which we would want to fix
later.

Thanks.

Re: [PATCH v2 8/9] doc: notes: treat --stdin equally between copy/remove

[Junio C Hamano]

kristofferhaugsbakk@fastmail.com writes:

>  `--stdin`::
> -	Also read the object names to remove notes from the standard
> -	input (there is no reason you cannot combine this with object
> -	names from the command line).
> +	For `remove` and `copy`. See the respective subcommands.

Let's phrase "Only valid for A and B".

Otherwise, looks good.  Thanks.

[PATCH v3 0/9] doc: --stdin on notes and core.commentChar mentions

[kristofferhaugsbakk]

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

I wanted to fix `--stdin` in the git-notes(1) documentation.  Then I
found some other things on that doc as well as things to do with
`core.commentChar`.

§ Changes in v3

Suggestions on patches 6 and 8 were implemented.  See the patch notes
and the interdiff.

Kristoffer Haugsbakk (9):
  doc: stripspace: mention where the default comes from
  doc: config: mention core.commentChar on commit.cleanup
  doc: notes: split out options with negated forms
  doc: notes: rework --[no-]stripspace
  doc: notes: remove stripspace discussion from other options
  doc: notes: clearly state that --stripspace is the default
  doc: notes: point out copy --stdin use with argv
  doc: notes: treat --stdin equally between copy/remove
  doc: notes: use stuck form throughout

 Documentation/config/commit.adoc  |  7 ++--
 Documentation/git-notes.adoc      | 54 ++++++++++++++++++-------------
 Documentation/git-stripspace.adoc |  3 +-
 3 files changed, 38 insertions(+), 26 deletions(-)

Interdiff against v2:
diff --git a/Documentation/git-notes.adoc b/Documentation/git-notes.adoc
index 43436daeccc..46a232ca718 100644
--- a/Documentation/git-notes.adoc
+++ b/Documentation/git-notes.adoc
@@ -197,7 +197,8 @@ OPTIONS
 `-C`/`--reuse-message`. However, keep in mind that this depends on the
 order of similar options. For example, for `-C <object> -m<message>`,
 `--stripspace` will be used because the default for `-m` overrides the
-previous `-C`.
+previous `-C`. This is a known limitation that may be fixed in the
+future.
 
 `--ref=<ref>`::
 	Manipulate the notes tree in _<ref>_.  This overrides
@@ -211,7 +212,7 @@ previous `-C`.
 	object that does not have notes attached to it.
 
 `--stdin`::
-	For `remove` and `copy`. See the respective subcommands.
+	Only valid for `remove` and `copy`. See the respective subcommands.
 
 `-n`::
 `--dry-run`::
Range-diff against v2:
 1:  bf3ea7f23c0 =  1:  bf3ea7f23c0 doc: stripspace: mention where the default comes from
 2:  e9cf956a824 =  2:  e9cf956a824 doc: config: mention core.commentChar on commit.cleanup
 3:  14dc58120e3 =  3:  14dc58120e3 doc: notes: split out options with negated forms
 4:  c68a91f81ba =  4:  c68a91f81ba doc: notes: rework --[no-]stripspace
 5:  f4755040f38 =  5:  f4755040f38 doc: notes: remove stripspace discussion from other options
 6:  be89c3349d2 !  6:  184cf032abf doc: notes: clearly state that --stripspace is the default
    @@ Commit message
         Clearly state when which of the regular and negated form of the
         option take effect.[1]
     
    +    Also mention the subtle behavior that occurs when you mix options like
    +    `-m` and `-C`, including a note that it might be fixed in the future.
    +    The topic was brought up on v8 of the `--separator` series.[2][3]
    +
         [1]: https://lore.kernel.org/git/xmqqcyct1mtq.fsf@gitster.g/
    +    [2]: https://lore.kernel.org/git/xmqq4jp326oj.fsf@gitster.g/
    +    † 3: v11 was the version that landed
     
    +    Helped-by: Junio C Hamano <gitster@pobox.com>
         Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
     
     
      ## Notes (series) ##
    +    v3:
    +    • Mention that it is a bug (“known limitation”) which might be fixed.
    +
    +      Link: https://lore.kernel.org/git/xmqqiklrvwl4.fsf@gitster.g/
    +    • Message: discuss this new “subtle behavior” part
         v2:
         • New
         • The `--` are to prevent the new paragraph from becoming a continuation
    @@ Documentation/git-notes.adoc: OPTIONS
     +`-C`/`--reuse-message`. However, keep in mind that this depends on the
     +order of similar options. For example, for `-C <object> -m<message>`,
     +`--stripspace` will be used because the default for `-m` overrides the
    -+previous `-C`.
    ++previous `-C`. This is a known limitation that may be fixed in the
    ++future.
      
      `--ref <ref>`::
      	Manipulate the notes tree in _<ref>_.  This overrides
 7:  d8a22847a7d =  7:  e18472f735d doc: notes: point out copy --stdin use with argv
 8:  3e8ecf1b668 !  8:  530dd953170 doc: notes: treat --stdin equally between copy/remove
    @@ Commit message
     
     
      ## Notes (series) ##
    +    v3:
    +    • Rephrase to “Only valid for”
    +
    +      Link: https://lore.kernel.org/git/xmqqecwfvwdu.fsf@gitster.g/
         v2:
         • On --stdin: just refer to the respective subcommands and stop there.
           As suggested.
    @@ Documentation/git-notes.adoc: When done, the user can either finalize the merge
      
      `prune`::
      	Remove all notes for non-existing/unreachable objects.
    -@@ Documentation/git-notes.adoc: previous `-C`.
    +@@ Documentation/git-notes.adoc: future.
      	object that does not have notes attached to it.
      
      `--stdin`::
     -	Also read the object names to remove notes from the standard
     -	input (there is no reason you cannot combine this with object
     -	names from the command line).
    -+	For `remove` and `copy`. See the respective subcommands.
    ++	Only valid for `remove` and `copy`. See the respective subcommands.
      
      `-n`::
      `--dry-run`::
 9:  73bdcaecae5 !  9:  7751330daa4 doc: notes: use stuck form throughout
    @@ Notes (series)
     
      ## Documentation/git-notes.adoc ##
     @@ Documentation/git-notes.adoc: order of similar options. For example, for `-C <object> -m<message>`,
    - `--stripspace` will be used because the default for `-m` overrides the
    - previous `-C`.
    + previous `-C`. This is a known limitation that may be fixed in the
    + future.
      
     -`--ref <ref>`::
     +`--ref=<ref>`::

base-commit: cb96e1697ad6e54d11fc920c95f82977f8e438f8
-- 
2.49.0.780.g892193c3f50

[PATCH v3 1/9] doc: stripspace: mention where the default comes from

[kristofferhaugsbakk]

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

Also quote `#` in line with the modern formatting convention.

Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---

Notes (series):
    v2:
    • More terse mention of the default as well as the configuration
      variable.  Don’t link to git-config(1), there’s no real need.
    
      Link: https://lore.kernel.org/git/xmqqjz6bhzkm.fsf@gitster.g/
    v1:
    • “modern formatting convention”
    
      It looks like characters are quoted with backticks in the commits I’ve
      seen by Jean-Noël Avila lately.

 Documentation/git-stripspace.adoc | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/Documentation/git-stripspace.adoc b/Documentation/git-stripspace.adoc
index a293327581a..37287f211f0 100644
--- a/Documentation/git-stripspace.adoc
+++ b/Documentation/git-stripspace.adoc
@@ -37,7 +37,8 @@ OPTIONS
 -------
 -s::
 --strip-comments::
-	Skip and remove all lines starting with a comment character (default '#').
+	Skip and remove all lines starting with a comment character
+	(`core.commentChar`, default `#`).
 
 -c::
 --comment-lines::
-- 
2.49.0.780.g892193c3f50

[PATCH v3 2/9] doc: config: mention core.commentChar on commit.cleanup

[kristofferhaugsbakk]

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

Mention it in parentheses since we are in a configuration context.
Refer to the default as such, not as “the” character.

Also don’t mention `#` again; just say “comment character”.

Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---
 Documentation/config/commit.adoc | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/Documentation/config/commit.adoc b/Documentation/config/commit.adoc
index d3f4624fd27..208ae76c816 100644
--- a/Documentation/config/commit.adoc
+++ b/Documentation/config/commit.adoc
@@ -8,10 +8,11 @@ endif::git-commit[]
 	This setting overrides the default of the `--cleanup` option in
 	`git commit`. {see-git-commit} Changing the default can be useful
 	when you always want to keep lines that begin
-	with the comment character `#` in your log message, in which case you
+	with the comment character (`core.commentChar`, default `#`)
+	in your log message, in which case you
 	would do `git config commit.cleanup whitespace` (note that you will
-	have to remove the help lines that begin with `#` in the commit log
-	template yourself, if you do this).
+	have to remove the help lines that begin with the comment character
+	in the commit log template yourself, if you do this).
 
 `commit.gpgSign`::
 	A boolean to specify whether all commits should be GPG signed.
-- 
2.49.0.780.g892193c3f50

[PATCH v3 3/9] doc: notes: split out options with negated forms

[kristofferhaugsbakk]

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

Split these out so that they are easier to search for.[1]

[1]: https://lore.kernel.org/git/xmqqcyct1mtq.fsf@gitster.g/

Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---

Notes (series):
    v2:
    • Message: Use “negated form” since that seems more typical

 Documentation/git-notes.adoc | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/Documentation/git-notes.adoc b/Documentation/git-notes.adoc
index bcfe3dacd3f..8706b33f2ee 100644
--- a/Documentation/git-notes.adoc
+++ b/Documentation/git-notes.adoc
@@ -174,14 +174,16 @@ OPTIONS
 	Allow an empty note object to be stored. The default behavior is
 	to automatically remove empty notes.
 
-`--[no-]separator`::
 `--separator=<paragraph-break>`::
+`--separator`::
+`--no-separator`::
 	Specify a string used as a custom inter-paragraph separator
 	(a newline is added at the end as needed). If `--no-separator`, no
 	separators will be added between paragraphs.  Defaults to a blank
 	line.
 
-`--[no-]stripspace`::
+`--stripspace`::
+`--no-stripspace`::
 	Strip leading and trailing whitespace from the note message.
 	Also strip out empty lines other than a single line between
 	paragraphs. Lines starting with `#` will be stripped out
-- 
2.49.0.780.g892193c3f50

[PATCH v3 4/9] doc: notes: rework --[no-]stripspace

[kristofferhaugsbakk]

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

Document this option by copying the bullet list from git-stripspace(1).
A bullet list is cleaner when there are this many points to consider.
We also get a more standardized description of the multiple-blank-lines
behavior.  Compare the repeating (git-notes(1)):

    empty lines other than a single line between paragraphs

With (git-stripspace(1)):

    multiple consecutive empty lines

And:

    leading [...] whitespace

With:

    empty lines from the beginning

Leading whitespace in the form of spaces (indentation) are not removed.
However, empty lines at the start of the message are removed.

Note that we drop the mentions of comment line handling because they are
wrong; this option does not control how lines which can be recognized as
comment lines are handled.  Only interactivity controls that:

• Comment lines are stripped after editing interactively
• Lines which could be recognized as comment lines are left alone when
  the message is given non-interactively

So it is misleading to document the comment line behavior on
this option.

Further, the text is wrong:

    Lines starting with `#` will be stripped out in non-editor cases
    like `-m`, [...]

Comment lines are still indirectly discussed on other options.  We will
deal with them in the next commit.

Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---

Notes (series):
    v2:
    • New
    • Together with one other other patch replaces v1 patch “doc: notes:
      mention comment character configuration”
    • I figured out that mentioning the comment character/comment lines
      doesn’t make sense here.  So all attempts to rephrase “comment
      character” or “lines that start with `#`” are gone

 Documentation/git-notes.adoc | 12 +++++++-----
 1 file changed, 7 insertions(+), 5 deletions(-)

diff --git a/Documentation/git-notes.adoc b/Documentation/git-notes.adoc
index 8706b33f2ee..d672794a942 100644
--- a/Documentation/git-notes.adoc
+++ b/Documentation/git-notes.adoc
@@ -184,11 +184,13 @@ OPTIONS
 
 `--stripspace`::
 `--no-stripspace`::
-	Strip leading and trailing whitespace from the note message.
-	Also strip out empty lines other than a single line between
-	paragraphs. Lines starting with `#` will be stripped out
-	in non-editor cases like `-m`, `-F` and `-C`, but not in
-	editor case like `git notes edit`, `-c`, etc.
+	Clean up whitespace. Specifically (see
+	linkgit:git-stripspace[1]):
++
+- remove trailing whitespace from all lines
+- collapse multiple consecutive empty lines into one empty line
+- remove empty lines from the beginning and end of the input
+- add a missing `\n` to the last line if necessary.
 
 `--ref <ref>`::
 	Manipulate the notes tree in _<ref>_.  This overrides
-- 
2.49.0.780.g892193c3f50

[PATCH v3 5/9] doc: notes: remove stripspace discussion from other options

[kristofferhaugsbakk]

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

Cleaning up whitespace in metadata is typical porcelain behavior and
this default does not need to be pointed out.[1]  Only speak up when
the default `--stripspace` is not used.

Also remove all misleading mentions of comment lines in the process;
see the previous commit.

Also remove the period that trails the parenthetical here.

† 1: See `-F` in git-commit(1) which has nothing to say about whitespace
    cleanup.  The cleanup discussion is on `--cleanup`.

Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---

Notes (series):
    v2:
    • New
    • Together with one other patch replaces v1 patch “doc: notes:
      mention comment character configuration”
    • I figured out that mentioning the comment character/comment lines
      doesn’t make sense here.  So all attempts to rephrase “comment
      character” or “lines that start with `#`” are gone

 Documentation/git-notes.adoc | 12 ++----------
 1 file changed, 2 insertions(+), 10 deletions(-)

diff --git a/Documentation/git-notes.adoc b/Documentation/git-notes.adoc
index d672794a942..383e8bca685 100644
--- a/Documentation/git-notes.adoc
+++ b/Documentation/git-notes.adoc
@@ -144,26 +144,18 @@ OPTIONS
 	Use the given note message (instead of prompting).
 	If multiple `-m` options are given, their values
 	are concatenated as separate paragraphs.
-	Lines starting with `#` and empty lines other than a
-	single line between paragraphs will be stripped out.
-	If you wish to keep them verbatim, use `--no-stripspace`.
 
 `-F <file>`::
 `--file=<file>`::
 	Take the note message from the given file.  Use `-` to
 	read the note message from the standard input.
-	Lines starting with `#` and empty lines other than a
-	single line between paragraphs will be stripped out.
-	If you wish to keep them verbatim, use `--no-stripspace`.
 
 `-C <object>`::
 `--reuse-message=<object>`::
 	Take the given blob object (for example, another note) as the
 	note message. (Use `git notes copy <object>` instead to
-	copy notes between objects.).  By default, message will be
-	copied verbatim, but if you wish to strip out the lines
-	starting with `#` and empty lines other than a single line
-	between paragraphs, use with `--stripspace` option.
+	copy notes between objects.)  Implies `--no-stripspace` since
+	the default behavior is to copy the message verbatim.
 
 `-c <object>`::
 `--reedit-message=<object>`::
-- 
2.49.0.780.g892193c3f50

[PATCH v3 6/9] doc: notes: clearly state that --stripspace is the default

[kristofferhaugsbakk]

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

Clearly state when which of the regular and negated form of the
option take effect.[1]

Also mention the subtle behavior that occurs when you mix options like
`-m` and `-C`, including a note that it might be fixed in the future.
The topic was brought up on v8 of the `--separator` series.[2][3]

[1]: https://lore.kernel.org/git/xmqqcyct1mtq.fsf@gitster.g/
[2]: https://lore.kernel.org/git/xmqq4jp326oj.fsf@gitster.g/
† 3: v11 was the version that landed

Helped-by: Junio C Hamano <gitster@pobox.com>
Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---

Notes (series):
    v3:
    • Mention that it is a bug (“known limitation”) which might be fixed.
    
      Link: https://lore.kernel.org/git/xmqqiklrvwl4.fsf@gitster.g/
    • Message: discuss this new “subtle behavior” part
    v2:
    • New
    • The `--` are to prevent the new paragraph from becoming a continuation
      of the last bullet point
    • Junio pointed out that I didn’t go over the part about checking
      which variant (regular or negation) are the default.  See the link:
    
      https://lore.kernel.org/git/xmqqcyct1mtq.fsf@gitster.g/
    
      I decided to do this on this series.
    
      Link: https://lore.kernel.org/git/xmqqfrgzhzbp.fsf@gitster.g/
    • The last part of the paragraph is based on the commit message of
      c4e2aa7d45f (notes.c: introduce "--[no-]stripspace" option,
      2023-05-27).
    
      See the review on the patch:
    
         https://lore.kernel.org/git/xmqq4jp326oj.fsf@gitster.g/
    
      There was concern about the order of options:
    
          >     ... One more thing need to note is "the order of
          >     the options matter", [...]
    
          This sounds more like a design/implementation mistake that we may
          want to fix.
    
      This new part is supposed to address that.

 Documentation/git-notes.adoc | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/Documentation/git-notes.adoc b/Documentation/git-notes.adoc
index 383e8bca685..ef5a939516e 100644
--- a/Documentation/git-notes.adoc
+++ b/Documentation/git-notes.adoc
@@ -179,10 +179,19 @@ OPTIONS
 	Clean up whitespace. Specifically (see
 	linkgit:git-stripspace[1]):
 +
+--
 - remove trailing whitespace from all lines
 - collapse multiple consecutive empty lines into one empty line
 - remove empty lines from the beginning and end of the input
 - add a missing `\n` to the last line if necessary.
+--
++
+`--stripspace` is the default except for
+`-C`/`--reuse-message`. However, keep in mind that this depends on the
+order of similar options. For example, for `-C <object> -m<message>`,
+`--stripspace` will be used because the default for `-m` overrides the
+previous `-C`. This is a known limitation that may be fixed in the
+future.
 
 `--ref <ref>`::
 	Manipulate the notes tree in _<ref>_.  This overrides
-- 
2.49.0.780.g892193c3f50

[PATCH v3 7/9] doc: notes: point out copy --stdin use with argv

[kristofferhaugsbakk]

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

Unlike `remove --stdin`, this option cannot be combined with object
names given via the command line.

Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---
 Documentation/git-notes.adoc | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/Documentation/git-notes.adoc b/Documentation/git-notes.adoc
index ef5a939516e..9ce71ec3455 100644
--- a/Documentation/git-notes.adoc
+++ b/Documentation/git-notes.adoc
@@ -87,6 +87,9 @@ In `--stdin` mode, take lines in the format
 on standard input, and copy the notes from each _<from-object>_ to its
 corresponding _<to-object>_.  (The optional _<rest>_ is ignored so that
 the command can read the input given to the `post-rewrite` hook.)
++
+`--stdin` cannot be combined with object names given on the command
+line.
 
 `append`::
 	Append new message(s) given by `-m` or `-F` options to an
-- 
2.49.0.780.g892193c3f50

[PATCH v3 8/9] doc: notes: treat --stdin equally between copy/remove

[kristofferhaugsbakk]

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

46538012d94 (notes remove: --stdin reads from the standard input,
2011-05-18) added `--stdin` for the `remove` subcommand, documenting it
in the “Options” section.  But `copy --stdin` was added before that, in
160baa0d9cb (notes: implement 'git notes copy --stdin', 2010-03-12).

Treat this option equally between the two subcommands:

• remove: mention `--stdin` on the subcommand as well, like for `copy`
• copy: mention it as well under the option documentation

Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---

Notes (series):
    v3:
    • Rephrase to “Only valid for”
    
      Link: https://lore.kernel.org/git/xmqqecwfvwdu.fsf@gitster.g/
    v2:
    • On --stdin: just refer to the respective subcommands and stop there.
      As suggested.
    
      Link: https://lore.kernel.org/git/xmqq34czhyz8.fsf@gitster.g/

 Documentation/git-notes.adoc | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/Documentation/git-notes.adoc b/Documentation/git-notes.adoc
index 9ce71ec3455..397f6caa92a 100644
--- a/Documentation/git-notes.adoc
+++ b/Documentation/git-notes.adoc
@@ -127,6 +127,10 @@ When done, the user can either finalize the merge with
 	giving zero or one object from the command line, this is
 	equivalent to specifying an empty note message to
 	the `edit` subcommand.
++
+In `--stdin` mode, also remove the object names given on standard
+input. In other words, `--stdin` can be combined with object names from
+the command line.
 
 `prune`::
 	Remove all notes for non-existing/unreachable objects.
@@ -208,9 +212,7 @@ future.
 	object that does not have notes attached to it.
 
 `--stdin`::
-	Also read the object names to remove notes from the standard
-	input (there is no reason you cannot combine this with object
-	names from the command line).
+	Only valid for `remove` and `copy`. See the respective subcommands.
 
 `-n`::
 `--dry-run`::
-- 
2.49.0.780.g892193c3f50

[PATCH v3 9/9] doc: notes: use stuck form throughout

[kristofferhaugsbakk]

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

gitcli(7) recommends the *stuck form*.  `--ref` is the only one which
does not use it.

Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---

Notes (series):
    v2:
    • New
    • I didn’t spot this in the first round.  Hopefully it’s fine to include
      it as well while we are editing this file.  I would consider making a
      separate thread if I wasn’t editing nearby hunks.

 Documentation/git-notes.adoc | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/git-notes.adoc b/Documentation/git-notes.adoc
index 397f6caa92a..46a232ca718 100644
--- a/Documentation/git-notes.adoc
+++ b/Documentation/git-notes.adoc
@@ -200,7 +200,7 @@ order of similar options. For example, for `-C <object> -m<message>`,
 previous `-C`. This is a known limitation that may be fixed in the
 future.
 
-`--ref <ref>`::
+`--ref=<ref>`::
 	Manipulate the notes tree in _<ref>_.  This overrides
 	`GIT_NOTES_REF` and the `core.notesRef` configuration.  The ref
 	specifies the full refname when it begins with `refs/notes/`; when it
-- 
2.49.0.780.g892193c3f50

Re: [PATCH v3 0/9] doc: --stdin on notes and core.commentChar mentions

[Junio C Hamano]

kristofferhaugsbakk@fastmail.com writes:

> From: Kristoffer Haugsbakk <code@khaugsbakk.name>
>
> I wanted to fix `--stdin` in the git-notes(1) documentation.  Then I
> found some other things on that doc as well as things to do with
> `core.commentChar`.

Looking really good.  Let me mark the topic for 'next'.

Thanks.