doc: --stdin on notes and core.commentChar mentions
cover doc: --stdin on notes and core.commentChar mentions
From: Kristoffer Haugsbakk <[email protected]>
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
Signature · 1 line
2.49.0.780.g892193c3f50
PATCH 1/6 doc: stripspace: mention where the default comes from
From: Kristoffer Haugsbakk <[email protected]>
Also quote # in line with the modern formatting convention.
---
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(-)
Documentation/git-stripspace.adoc +2 -1
@@ -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::
Signature · 1 line
2.49.0.780.g892193c3f50
Re: [PATCH 1/6] doc: stripspace: mention where the default comes from
Quoted 21 lines · [email protected] writes:
From: Kristoffer Haugsbakk <[email protected]>
Also quote
#in line with the modern formatting convention.Signed-off-by Kristoffer Haugsbakk <[email protected]>---
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(-)Documentation/git-stripspace.adoc +0
-0
Documentation/git-stripspace.adoc OPTIONS · line 41
Quoted 6 lines
Documentation/git-stripspace.adoc +2
-1@@ -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 1/6] doc: stripspace: mention where the default comes from
Quoted 19 lines · Junio C Hamano
Documentation/git-stripspace.adoc OPTIONS · line 41
Quoted 11 lines
Documentation/git-stripspace.adoc +2
-1@@ -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#.
Quoted 6 lines
The way you phrased is syntactically easier to parse, but to some readers, the readon why they are encouraged to learn about the
core.commentCharconfiguration 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.
Signature · 1 line
Kristoffer
PATCH 2/6 doc: config: mention core.commentChar on commit.cleanup
In reply to [email protected]From: Kristoffer Haugsbakk <[email protected]>
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”.
--- Documentation/config/commit.adoc | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-)
Documentation/config/commit.adoc +4 -3
@@ -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.
Signature · 1 line
2.49.0.780.g892193c3f50
PATCH 3/6 doc: notes: split out options with negations
In reply to [email protected]From: Kristoffer Haugsbakk <[email protected]>
Split these out so that they are easier to search for.[1]
[1]: https://lore.kernel.org/git/[email protected]/
--- Documentation/git-notes.adoc | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-)
Documentation/git-notes.adoc +4 -2
@@ -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
Signature · 1 line
2.49.0.780.g892193c3f50
Re: [PATCH 3/6] doc: notes: split out options with negations
Documentation/git-notes.adoc OPTIONS · line 183
Quoted 8 lines · [email protected] writes:
-
--[no-]separator::
--separator=<paragraph-break>::
+--separator::
+--no-separator::Documentation/git-notes.adoc +0
-0Specify 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.
Documentation/git-notes.adoc OPTIONS · line 189
Quoted 6 lines
-
--[no-]stripspace::
+--stripspace::
+--no-stripspace::Documentation/git-notes.adoc +0
-0Strip 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 3/6] doc: notes: split out options with negations
Quoted 20 lines · Junio C Hamano
Documentation/git-notes.adoc OPTIONS · line 183
Quoted 8 lines · [email protected] writes:
-
--[no-]separator::
--separator=<paragraph-break>::
+--separator::
+--no-separator::Documentation/git-notes.adoc +0
-0Specify 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.
Documentation/git-notes.adoc OPTIONS · line 189
Quoted 6 lines
-
--[no-]stripspace::
+--stripspace::
+--no-stripspace::Documentation/git-notes.adoc +0
-0Strip 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
Quoted 3 lines
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 3/6] doc: notes: split out options with negations
Quoted 9 lines · Junio C Hamano
Quoted 3 lines
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.
Quoted 5 lines
[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.
Signature · 1 line
Kristoffer
Re: [PATCH 3/6] doc: notes: split out options with negations
Quoted 5 lines · Kristoffer Haugsbakk
Quoted 5 lines
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.
Quoted 8 lines
Quoted 5 lines
[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 [*].
Quoted 1 line
I’ll fix it on a separate patch in the next version.
Thanks.
[Reference]
Re: [PATCH 3/6] doc: notes: split out options with negations
Quoted 1 line · Junio C Hamano
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.
Signature · 1 line
Kristoffer
PATCH 4/6 doc: notes: mention comment character configuration
In reply to [email protected]From: Kristoffer Haugsbakk <[email protected]>
--- Documentation/git-notes.adoc | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-)
Documentation/git-notes.adoc +4 -1
@@ -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
Signature · 1 line
2.49.0.780.g892193c3f50
Re: [PATCH 4/6] doc: notes: mention comment character configuration
Quoted 15 lines · [email protected] writes:
From: Kristoffer Haugsbakk <[email protected]>
Signed-off-by Kristoffer Haugsbakk <[email protected]>--- Documentation/git-notes.adoc | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-)Documentation/git-notes.adoc +0
-0@@ -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
Documentation/git-notes.adoc OPTIONS · line 197
Quoted 10 lines
Documentation/git-notes.adoc +4
-1- 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.
PATCH 5/6 doc: notes: point out copy --stdin use with argv
In reply to [email protected]From: Kristoffer Haugsbakk <[email protected]>
Unlike remove --stdin, this option cannot be combined with object names given via the command line.
--- Documentation/git-notes.adoc | 3 +++ 1 file changed, 3 insertions(+)
Documentation/git-notes.adoc +3 -0
@@ -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
Signature · 1 line
2.49.0.780.g892193c3f50
Re: [PATCH 5/6] doc: notes: point out copy --stdin use with argv
Quoted 9 lines · [email protected] writes:
From: Kristoffer Haugsbakk <[email protected]>
Unlike
remove --stdin, this option cannot be combined with object names given via the command line.Signed-off-by Kristoffer Haugsbakk <[email protected]>--- Documentation/git-notes.adoc | 3 +++ 1 file changed, 3 insertions(+)
OK.
Quoted 14 lines
Documentation/git-notes.adoc +3
-0@@ -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
PATCH 6/6 doc: notes: treat --stdin equally between copy/remove
In reply to [email protected]From: Kristoffer Haugsbakk <[email protected]>
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
--- Documentation/git-notes.adoc | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-)
Documentation/git-notes.adoc +7 -3
@@ -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`::
Signature · 1 line
2.49.0.780.g892193c3f50
Re: [PATCH 6/6] doc: notes: treat --stdin equally between copy/remove
Quoted 33 lines · [email protected] writes:
From: Kristoffer Haugsbakk <[email protected]>
46538012d94(notes remove: --stdin reads from the standard input, 2011-05-18) added--stdinfor theremovesubcommand, documenting it in the “Options” section. Butcopy --stdinwas added before that, in160baa0d9cb(notes: implement 'git notes copy --stdin', 2010-03-12).Treat this option equally between the two subcommands:
• remove: mention
--stdinon the subcommand as well, like forcopy
• copy: mention it as well under the option documentationSigned-off-by Kristoffer Haugsbakk <[email protected]>--- Documentation/git-notes.adoc | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-)Documentation/git-notes.adoc +4
-0@@ -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.
Documentation/git-notes.adoc See `core.commentChar` in linkgit:git-config[1]. · line 213
Quoted 6 lines
Documentation/git-notes.adoc +0
-3@@ -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.
Documentation/git-notes.adoc See `core.commentChar` in linkgit:git-config[1]. · line 217
Quoted 3 lines
Documentation/git-notes.adoc +3
-0+ 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 6/6] doc: notes: treat --stdin equally between copy/remove
Quoted 11 lines · Junio C Hamano
Documentation/git-notes.adoc See `core.commentChar` in linkgit:git-config[1]. · line 217
Quoted 3 lines
Documentation/git-notes.adoc +3
-0+ 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.
Quoted 6 lines
It may be simpler to just say
Only valid for
removeandcopy. See the respective subcommands.and stop there.
Yep I agree. Just leave it to the subcommand sections.
Signature · 1 line
Kristoffer Haugsbakk
Re: [PATCH 6/6] doc: notes: treat --stdin equally between copy/remove
In reply to [email protected]Quoted 8 lines · On Tue, May 20, 2025 at 1:58 PM <[email protected]> wrote:
From: Kristoffer Haugsbakk <[email protected]>
46538012d94(notes remove: --stdin reads from the standard input, 2011-05-18) added--stdinfor theremovesubcommand, documenting it in the “Options” section. Butcopy --stdinwas added before that, in160baa0d9cb(notes: implement 'git notes copy --stdin', 2010-03-12).
Quoted 4 lines
Treat this option equally between the two subcommands:
• remove: mention
--stdinon the subcommand as well, like forcopy
• 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!
Signature · 1 line
D. Ben Knoble
Re: [PATCH 6/6] doc: notes: treat --stdin equally between copy/remove
Quoted 6 lines · D. Ben Knoble
Quoted 2 lines · On Tue, May 20, 2025 at 1:58 PM <[email protected]> wrote:
• remove: mention
--stdinon the subcommand as well, like forcopy
• copy: mention it as well under the option documentationOoh, 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
Quoted 9 lines · Kristoffer Haugsbakk
Quoted 6 lines · D. Ben Knoble
Quoted 2 lines · On Tue, May 20, 2025 at 1:58 PM <[email protected]> wrote:
• remove: mention
--stdinon the subcommand as well, like forcopy
• copy: mention it as well under the option documentationOoh, 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?
v2 cover doc: --stdin on notes and core.commentChar mentions
In reply to [email protected]From: Kristoffer Haugsbakk <[email protected]>
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:
Documentation/git-notes.adoc +18 -21
@@ -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`::
Documentation/git-stripspace.adoc +2 -2
@@ -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 <[email protected]>
## 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
+
+ ## 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 <[email protected]>
## 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.
+
+ ## 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 <[email protected]>
## 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.
## 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
+
+ ## Notes (series) ##
+ v2:
+ • On --stdin: just refer to the respective subcommands and stop there.
+ As suggested.
+
+ Link: https://lore.kernel.org/git/[email protected]/
+
## 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
Signature · 1 line
2.49.0.780.g892193c3f50
PATCH v2 1/9 doc: stripspace: mention where the default comes from
From: Kristoffer Haugsbakk <[email protected]>
Also quote # in line with the modern formatting convention.
---
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.
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(-)
Documentation/git-stripspace.adoc +2 -1
@@ -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::
Signature · 1 line
2.49.0.780.g892193c3f50
PATCH v2 2/9 doc: config: mention core.commentChar on commit.cleanup
In reply to [email protected]From: Kristoffer Haugsbakk <[email protected]>
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”.
--- Documentation/config/commit.adoc | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-)
Documentation/config/commit.adoc +4 -3
@@ -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.
Signature · 1 line
2.49.0.780.g892193c3f50
PATCH v2 3/9 doc: notes: split out options with negated forms
In reply to [email protected]From: Kristoffer Haugsbakk <[email protected]>
Split these out so that they are easier to search for.[1]
[1]: https://lore.kernel.org/git/[email protected]/
---
Notes (series):
v2:
• Message: Use “negated form” since that seems more typical
Documentation/git-notes.adoc | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-)
Documentation/git-notes.adoc +4 -2
@@ -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
Signature · 1 line
2.49.0.780.g892193c3f50
PATCH v2 4/9 doc: notes: rework --[no-]stripspace
In reply to [email protected]From: Kristoffer Haugsbakk <[email protected]>
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.
---
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(-)
Documentation/git-notes.adoc +7 -5
@@ -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
Signature · 1 line
2.49.0.780.g892193c3f50
PATCH v2 5/9 doc: notes: remove stripspace discussion from other options
In reply to [email protected]From: Kristoffer Haugsbakk <[email protected]>
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.
---
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(-)
Documentation/git-notes.adoc +2 -10
@@ -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>`::
Signature · 1 line
2.49.0.780.g892193c3f50
PATCH v2 6/9 doc: notes: clearly state that --stripspace is the default
In reply to [email protected]From: Kristoffer Haugsbakk <[email protected]>
Clearly state when which of the regular and negated form of the option take effect.[1]
[1]: https://lore.kernel.org/git/[email protected]/
---
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/[email protected]/
I decided to do this on this series.
• 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/[email protected]/
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(+)
Documentation/git-notes.adoc +8 -0
@@ -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
Signature · 1 line
2.49.0.780.g892193c3f50
Re: [PATCH v2 6/9] doc: notes: clearly state that --stripspace is the default
Quoted 11 lines · [email protected] writes:
See the review on the patch:
https://lore.kernel.org/git/[email protected]/
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.
Documentation/git-notes.adoc OPTIONS · line 193
Quoted 7 lines
+--
++
+--stripspaceis the default except for +-C/--reuse-message. However, keep in mind that this depends on theDocumentation/git-notes.adoc +3
-0+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.
PATCH v2 7/9 doc: notes: point out copy --stdin use with argv
In reply to [email protected]From: Kristoffer Haugsbakk <[email protected]>
Unlike remove --stdin, this option cannot be combined with object names given via the command line.
--- Documentation/git-notes.adoc | 3 +++ 1 file changed, 3 insertions(+)
Documentation/git-notes.adoc +3 -0
@@ -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
Signature · 1 line
2.49.0.780.g892193c3f50
PATCH v2 8/9 doc: notes: treat --stdin equally between copy/remove
In reply to [email protected]From: Kristoffer Haugsbakk <[email protected]>
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
---
Notes (series):
v2:
• On --stdin: just refer to the respective subcommands and stop there. As suggested.
Documentation/git-notes.adoc | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-)
Documentation/git-notes.adoc +5 -3
@@ -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`::
Signature · 1 line
2.49.0.780.g892193c3f50
Re: [PATCH v2 8/9] doc: notes: treat --stdin equally between copy/remove
Documentation/git-notes.adoc previous `-C`. · line 214
Quoted 5 lines · [email protected] writes:
--stdin::Documentation/git-notes.adoc +1
-3- 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 v2 9/9 doc: notes: use stuck form throughout
In reply to [email protected]From: Kristoffer Haugsbakk <[email protected]>
gitcli(7) recommends the *stuck form*. --ref is the only one which does not use it.
---
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(-)
Documentation/git-notes.adoc +1 -1
@@ -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
Signature · 1 line
2.49.0.780.g892193c3f50
v3 cover doc: --stdin on notes and core.commentChar mentions
In reply to [email protected]From: Kristoffer Haugsbakk <[email protected]>
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:
Documentation/git-notes.adoc +3 -2
@@ -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/[email protected]/
+ [2]: https://lore.kernel.org/git/[email protected]/
+ † 3: v11 was the version that landed
+ Helped-by: Junio C Hamano <[email protected]>
## Notes (series) ##
+ v3:
+ • Mention that it is a bug (“known limitation”) which might be fixed.
+
+ Link: https://lore.kernel.org/git/[email protected]/
+ • 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/[email protected]/
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
Signature · 1 line
2.49.0.780.g892193c3f50
PATCH v3 1/9 doc: stripspace: mention where the default comes from
From: Kristoffer Haugsbakk <[email protected]>
Also quote # in line with the modern formatting convention.
---
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.
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(-)
Documentation/git-stripspace.adoc +2 -1
@@ -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::
Signature · 1 line
2.49.0.780.g892193c3f50
PATCH v3 2/9 doc: config: mention core.commentChar on commit.cleanup
In reply to [email protected]From: Kristoffer Haugsbakk <[email protected]>
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”.
--- Documentation/config/commit.adoc | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-)
Documentation/config/commit.adoc +4 -3
@@ -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.
Signature · 1 line
2.49.0.780.g892193c3f50
PATCH v3 3/9 doc: notes: split out options with negated forms
In reply to [email protected]From: Kristoffer Haugsbakk <[email protected]>
Split these out so that they are easier to search for.[1]
[1]: https://lore.kernel.org/git/[email protected]/
---
Notes (series):
v2:
• Message: Use “negated form” since that seems more typical
Documentation/git-notes.adoc | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-)
Documentation/git-notes.adoc +4 -2
@@ -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
Signature · 1 line
2.49.0.780.g892193c3f50
PATCH v3 4/9 doc: notes: rework --[no-]stripspace
In reply to [email protected]From: Kristoffer Haugsbakk <[email protected]>
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.
---
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(-)
Documentation/git-notes.adoc +7 -5
@@ -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
Signature · 1 line
2.49.0.780.g892193c3f50
PATCH v3 5/9 doc: notes: remove stripspace discussion from other options
In reply to [email protected]From: Kristoffer Haugsbakk <[email protected]>
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.
---
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(-)
Documentation/git-notes.adoc +2 -10
@@ -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>`::
Signature · 1 line
2.49.0.780.g892193c3f50
PATCH v3 6/9 doc: notes: clearly state that --stripspace is the default
In reply to [email protected]From: Kristoffer Haugsbakk <[email protected]>
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/[email protected]/
[2]: https://lore.kernel.org/git/[email protected]/
† 3: v11 was the version that landed
---
Notes (series):
v3:
• Mention that it is a bug (“known limitation”) which might be fixed.
• 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/[email protected]/
I decided to do this on this series.
• 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/[email protected]/
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(+)
Documentation/git-notes.adoc +9 -0
@@ -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
Signature · 1 line
2.49.0.780.g892193c3f50
PATCH v3 7/9 doc: notes: point out copy --stdin use with argv
In reply to [email protected]From: Kristoffer Haugsbakk <[email protected]>
Unlike remove --stdin, this option cannot be combined with object names given via the command line.
--- Documentation/git-notes.adoc | 3 +++ 1 file changed, 3 insertions(+)
Documentation/git-notes.adoc +3 -0
@@ -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
Signature · 1 line
2.49.0.780.g892193c3f50
PATCH v3 8/9 doc: notes: treat --stdin equally between copy/remove
In reply to [email protected]From: Kristoffer Haugsbakk <[email protected]>
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
---
Notes (series):
v3:
• Rephrase to “Only valid for”
v2:
• On --stdin: just refer to the respective subcommands and stop there. As suggested.
Documentation/git-notes.adoc | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-)
Documentation/git-notes.adoc +5 -3
@@ -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`::
Signature · 1 line
2.49.0.780.g892193c3f50
PATCH v3 9/9 doc: notes: use stuck form throughout
In reply to [email protected]From: Kristoffer Haugsbakk <[email protected]>
gitcli(7) recommends the *stuck form*. --ref is the only one which does not use it.
---
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(-)
Documentation/git-notes.adoc +1 -1
@@ -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
Signature · 1 line
2.49.0.780.g892193c3f50
Quoted 5 lines · [email protected] writes:
From: Kristoffer Haugsbakk <[email protected]>
I wanted to fix
--stdinin the git-notes(1) documentation. Then I found some other things on that doc as well as things to do withcore.commentChar.
Looking really good. Let me mark the topic for 'next'.
Thanks.