{"thread":{"id":"63486","subject":"[PATCH 0/6] doc: --stdin on notes and core.commentChar mentions","startedAt":"2025-05-20T17:58:05Z","lastAt":"2025-05-27T22:33:03Z","messageCount":44,"participants":["kristofferhaugsbakk@fastmail.com","Junio C Hamano","D. Ben Knoble","Kristoffer Haugsbakk"],"isPatch":true,"patchVersion":1,"patchTotal":6},"messages":[{"id":"518509","messageId":"cover.1747763769.git.code@khaugsbakk.name","threadId":"63486","inReplyTo":null,"subject":"[PATCH 0/6] doc: --stdin on notes and core.commentChar mentions","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2025-05-20T17:57:18Z","receivedAt":"2025-05-20T17:58:05Z","isPatch":true,"sender":{"key":"kristofferhaugsbakk@fastmail.com","avatar":null},"body":"From: Kristoffer Haugsbakk \n\nI wanted to fix `--stdin` in the git-notes(1) documentation. Then I\nfound some other things on that doc as well as things to do with\n`core.commentChar`.\n\nI was unsure how I should refer to the config since `core.commentChar`\nand `core.commentString` are aliases. I just went with the first since\nno other docs mention the second.\n\n§ CC\n\nPeff: for 9ccf3e9b22b (config: add core.commentString, 2024-03-27)\n\nTeng Long: for 3d6a3164649 (notes: introduce \"--no-separator\" option,\n2023-05-27)\n\nKristoffer Haugsbakk (6):\n doc: stripspace: mention where the default comes from\n doc: config: mention core.commentChar on commit.cleanup\n doc: notes: split out options with negations\n doc: notes: mention comment character configuration\n doc: notes: point out copy --stdin use with argv\n doc: notes: treat --stdin equally between copy/remove\n\n Documentation/config/commit.adoc | 7 ++++---\n Documentation/git-notes.adoc | 24 ++++++++++++++++++------\n Documentation/git-stripspace.adoc | 3 ++-\n 3 files changed, 24 insertions(+), 10 deletions(-)\n\n\nbase-commit: cb96e1697ad6e54d11fc920c95f82977f8e438f8\n-- \n2.49.0.780.g892193c3f50\n\n"},{"id":"518510","messageId":"630ef019786bdb0c7538cc9794a7ba53a0ac77d8.1747763769.git.code@khaugsbakk.name","threadId":"63486","inReplyTo":"cover.1747763769.git.code@khaugsbakk.name","subject":"[PATCH 1/6] doc: stripspace: mention where the default comes from","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2025-05-20T17:57:19Z","receivedAt":"2025-05-20T17:58:09Z","isPatch":true,"sender":{"key":"kristofferhaugsbakk@fastmail.com","avatar":null},"body":"From: Kristoffer Haugsbakk \n\nAlso quote `#` in line with the modern formatting convention.\n\nSigned-off-by: Kristoffer Haugsbakk \n---\n\nNotes (series):\n “modern formatting convention”\n \n It looks like characters are quoted with backticks in the commits I’ve\n seen by Jean-Noël Avila lately.\n\n Documentation/git-stripspace.adoc | 3 ++-\n 1 file changed, 2 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/git-stripspace.adoc b/Documentation/git-stripspace.adoc\nindex a293327581a..1132a4cf9a9 100644\n--- a/Documentation/git-stripspace.adoc\n+++ b/Documentation/git-stripspace.adoc\n@@ -37,7 +37,8 @@ OPTIONS\n -------\n -s::\n --strip-comments::\n-\tSkip and remove all lines starting with a comment character (default '#').\n+\tSkip and remove all lines starting with a comment character (default `#`).\n+\tSee `core.commentChar` in linkgit:git-config[1].\n \n -c::\n --comment-lines::\n-- \n2.49.0.780.g892193c3f50\n\n"},{"id":"518512","messageId":"b43b78aba63fe89fb0e85754f2124f96f3af01dd.1747763769.git.code@khaugsbakk.name","threadId":"63486","inReplyTo":"cover.1747763769.git.code@khaugsbakk.name","subject":"[PATCH 2/6] doc: config: mention core.commentChar on commit.cleanup","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2025-05-20T17:57:20Z","receivedAt":"2025-05-20T17:58:12Z","isPatch":true,"sender":{"key":"kristofferhaugsbakk@fastmail.com","avatar":null},"body":"From: Kristoffer Haugsbakk \n\nMention it in parentheses since we are in a configuration context.\nRefer to the default as such, not as “the” character.\n\nAlso don’t mention `#` again; just say “comment character”.\n\nSigned-off-by: Kristoffer Haugsbakk \n---\n Documentation/config/commit.adoc | 7 ++++---\n 1 file changed, 4 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/config/commit.adoc b/Documentation/config/commit.adoc\nindex d3f4624fd27..208ae76c816 100644\n--- a/Documentation/config/commit.adoc\n+++ b/Documentation/config/commit.adoc\n@@ -8,10 +8,11 @@ endif::git-commit[]\n \tThis setting overrides the default of the `--cleanup` option in\n \t`git commit`. {see-git-commit} Changing the default can be useful\n \twhen you always want to keep lines that begin\n-\twith the comment character `#` in your log message, in which case you\n+\twith the comment character (`core.commentChar`, default `#`)\n+\tin your log message, in which case you\n \twould do `git config commit.cleanup whitespace` (note that you will\n-\thave to remove the help lines that begin with `#` in the commit log\n-\ttemplate yourself, if you do this).\n+\thave to remove the help lines that begin with the comment character\n+\tin the commit log template yourself, if you do this).\n \n `commit.gpgSign`::\n \tA boolean to specify whether all commits should be GPG signed.\n-- \n2.49.0.780.g892193c3f50\n\n"},{"id":"518513","messageId":"d2b6864b7072faa2c804c98ce7758b666e11f00b.1747763769.git.code@khaugsbakk.name","threadId":"63486","inReplyTo":"cover.1747763769.git.code@khaugsbakk.name","subject":"[PATCH 3/6] doc: notes: split out options with negations","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2025-05-20T17:57:21Z","receivedAt":"2025-05-20T17:58:15Z","isPatch":true,"sender":{"key":"kristofferhaugsbakk@fastmail.com","avatar":null},"body":"From: Kristoffer Haugsbakk \n\nSplit these out so that they are easier to search for.[1]\n\n[1]: https://lore.kernel.org/git/xmqqcyct1mtq.fsf@gitster.g/\n\nSigned-off-by: Kristoffer Haugsbakk \n---\n Documentation/git-notes.adoc | 6 ++++--\n 1 file changed, 4 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/git-notes.adoc b/Documentation/git-notes.adoc\nindex bcfe3dacd3f..8706b33f2ee 100644\n--- a/Documentation/git-notes.adoc\n+++ b/Documentation/git-notes.adoc\n@@ -174,14 +174,16 @@ OPTIONS\n \tAllow an empty note object to be stored. The default behavior is\n \tto automatically remove empty notes.\n \n-`--[no-]separator`::\n `--separator=`::\n+`--separator`::\n+`--no-separator`::\n \tSpecify a string used as a custom inter-paragraph separator\n \t(a newline is added at the end as needed). If `--no-separator`, no\n \tseparators will be added between paragraphs. Defaults to a blank\n \tline.\n \n-`--[no-]stripspace`::\n+`--stripspace`::\n+`--no-stripspace`::\n \tStrip leading and trailing whitespace from the note message.\n \tAlso strip out empty lines other than a single line between\n \tparagraphs. Lines starting with `#` will be stripped out\n-- \n2.49.0.780.g892193c3f50\n\n"},{"id":"518514","messageId":"f3f54a3537f71d8d4e3755d93ce58cf6472a2b7a.1747763769.git.code@khaugsbakk.name","threadId":"63486","inReplyTo":"cover.1747763769.git.code@khaugsbakk.name","subject":"[PATCH 4/6] doc: notes: mention comment character configuration","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2025-05-20T17:57:22Z","receivedAt":"2025-05-20T17:58:18Z","isPatch":true,"sender":{"key":"kristofferhaugsbakk@fastmail.com","avatar":null},"body":"From: Kristoffer Haugsbakk \n\nSigned-off-by: Kristoffer Haugsbakk \n---\n Documentation/git-notes.adoc | 5 ++++-\n 1 file changed, 4 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/git-notes.adoc b/Documentation/git-notes.adoc\nindex 8706b33f2ee..1b714eb9e81 100644\n--- a/Documentation/git-notes.adoc\n+++ b/Documentation/git-notes.adoc\n@@ -186,9 +186,12 @@ OPTIONS\n `--no-stripspace`::\n \tStrip leading and trailing whitespace from the note message.\n \tAlso strip out empty lines other than a single line between\n-\tparagraphs. Lines starting with `#` will be stripped out\n+\tparagraphs. Lines starting with the comment character\n+\t(default `#`) will be stripped out\n \tin non-editor cases like `-m`, `-F` and `-C`, but not in\n \teditor case like `git notes edit`, `-c`, etc.\n++\n+See `core.commentChar` in linkgit:git-config[1].\n \n `--ref `::\n \tManipulate the notes tree in __. This overrides\n-- \n2.49.0.780.g892193c3f50\n\n"},{"id":"518515","messageId":"cbb177479cae24b85284d507beff4b7abe173dc8.1747763769.git.code@khaugsbakk.name","threadId":"63486","inReplyTo":"cover.1747763769.git.code@khaugsbakk.name","subject":"[PATCH 5/6] doc: notes: point out copy --stdin use with argv","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2025-05-20T17:57:23Z","receivedAt":"2025-05-20T17:58:22Z","isPatch":true,"sender":{"key":"kristofferhaugsbakk@fastmail.com","avatar":null},"body":"From: Kristoffer Haugsbakk \n\nUnlike `remove --stdin`, this option cannot be combined with object\nnames given via the command line.\n\nSigned-off-by: Kristoffer Haugsbakk \n---\n Documentation/git-notes.adoc | 3 +++\n 1 file changed, 3 insertions(+)\n\ndiff --git a/Documentation/git-notes.adoc b/Documentation/git-notes.adoc\nindex 1b714eb9e81..d2d7dac8d41 100644\n--- a/Documentation/git-notes.adoc\n+++ b/Documentation/git-notes.adoc\n@@ -87,6 +87,9 @@ In `--stdin` mode, take lines in the format\n on standard input, and copy the notes from each __ to its\n corresponding __. (The optional __ is ignored so that\n the command can read the input given to the `post-rewrite` hook.)\n++\n+`--stdin` cannot be combined with object names given on the command\n+line.\n \n `append`::\n \tAppend new message(s) given by `-m` or `-F` options to an\n-- \n2.49.0.780.g892193c3f50\n\n"},{"id":"518516","messageId":"68e5eb78040419ba64e256910501c7e37194b222.1747763769.git.code@khaugsbakk.name","threadId":"63486","inReplyTo":"cover.1747763769.git.code@khaugsbakk.name","subject":"[PATCH 6/6] doc: notes: treat --stdin equally between copy/remove","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2025-05-20T17:57:24Z","receivedAt":"2025-05-20T17:58:25Z","isPatch":true,"sender":{"key":"kristofferhaugsbakk@fastmail.com","avatar":null},"body":"From: Kristoffer Haugsbakk \n\n46538012d94 (notes remove: --stdin reads from the standard input,\n2011-05-18) added `--stdin` for the `remove` subcommand, documenting it\nin the “Options” section. But `copy --stdin` was added before that, in\n160baa0d9cb (notes: implement 'git notes copy --stdin', 2010-03-12).\n\nTreat this option equally between the two subcommands:\n\n• remove: mention `--stdin` on the subcommand as well, like for `copy`\n• copy: mention it as well under the option documentation\n\nSigned-off-by: Kristoffer Haugsbakk \n---\n Documentation/git-notes.adoc | 10 +++++++---\n 1 file changed, 7 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/git-notes.adoc b/Documentation/git-notes.adoc\nindex d2d7dac8d41..1542850eaaa 100644\n--- a/Documentation/git-notes.adoc\n+++ b/Documentation/git-notes.adoc\n@@ -127,6 +127,10 @@ When done, the user can either finalize the merge with\n \tgiving zero or one object from the command line, this is\n \tequivalent to specifying an empty note message to\n \tthe `edit` subcommand.\n++\n+In `--stdin` mode, also remove the object names given on standard\n+input. In other words, `--stdin` can be combined with object names from\n+the command line.\n \n `prune`::\n \tRemove all notes for non-existing/unreachable objects.\n@@ -208,9 +212,9 @@ See `core.commentChar` in linkgit:git-config[1].\n \tobject that does not have notes attached to it.\n \n `--stdin`::\n-\tAlso read the object names to remove notes from the standard\n-\tinput (there is no reason you cannot combine this with object\n-\tnames from the command line).\n+\tFor `remove` and `copy`. See the respective subcommands. This\n+\toption can be combined with object names given via the command\n+\tline for `remove`. However, this is not the case for `copy`.\n \n `-n`::\n `--dry-run`::\n-- \n2.49.0.780.g892193c3f50\n\n"},{"id":"518519","messageId":"xmqqjz6bhzkm.fsf@gitster.g","threadId":"63486","inReplyTo":"630ef019786bdb0c7538cc9794a7ba53a0ac77d8.1747763769.git.code@khaugsbakk.name","subject":"Re: [PATCH 1/6] doc: stripspace: mention where the default comes from","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-05-20T19:06:17Z","receivedAt":"2025-05-20T19:06:20Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"kristofferhaugsbakk@fastmail.com writes:\n\n> From: Kristoffer Haugsbakk \n>\n> Also quote `#` in line with the modern formatting convention.\n>\n> Signed-off-by: Kristoffer Haugsbakk \n> ---\n>\n> Notes (series):\n> “modern formatting convention”\n> \n> It looks like characters are quoted with backticks in the commits I’ve\n> seen by Jean-Noël Avila lately.\n>\n> Documentation/git-stripspace.adoc | 3 ++-\n> 1 file changed, 2 insertions(+), 1 deletion(-)\n>\n> diff --git a/Documentation/git-stripspace.adoc b/Documentation/git-stripspace.adoc\n> index a293327581a..1132a4cf9a9 100644\n> --- a/Documentation/git-stripspace.adoc\n> +++ b/Documentation/git-stripspace.adoc\n> @@ -37,7 +37,8 @@ OPTIONS\n> -------\n> -s::\n> --strip-comments::\n> -\tSkip and remove all lines starting with a comment character (default '#').\n> +\tSkip and remove all lines starting with a comment character (default `#`).\n> +\tSee `core.commentChar` in linkgit:git-config[1].\n\nI've seen this kind of thing treat the configuration as the first\nlevel default, with the hardcoded value as a fallback, i.e. spelling\nit more like this:\n\n ... a comment character. Defaults to `core.commentChar`, which\n in turn defaults to `#`.\n\nThe way you phrased is syntactically easier to parse, but to some\nreaders, the readon why they are encouraged to learn about the\n`core.commentChar` configuration may not be immediately obvious, so\nI dunno.\n\nThanks.\n"},{"id":"518520","messageId":"xmqqfrgzhzbp.fsf@gitster.g","threadId":"63486","inReplyTo":"d2b6864b7072faa2c804c98ce7758b666e11f00b.1747763769.git.code@khaugsbakk.name","subject":"Re: [PATCH 3/6] doc: notes: split out options with negations","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-05-20T19:11:38Z","receivedAt":"2025-05-20T19:11:41Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"kristofferhaugsbakk@fastmail.com writes:\n\n> -`--[no-]separator`::\n> `--separator=`::\n> +`--separator`::\n> +`--no-separator`::\n> \tSpecify a string used as a custom inter-paragraph separator\n> \t(a newline is added at the end as needed). If `--no-separator`, no\n> \tseparators will be added between paragraphs. Defaults to a blank\n> \tline.\n\nOK.\n\n> -`--[no-]stripspace`::\n> +`--stripspace`::\n> +`--no-stripspace`::\n> \tStrip leading and trailing whitespace from the note message.\n> \tAlso strip out empty lines other than a single line between\n> \tparagraphs. Lines starting with `#` will be stripped out\n\nTogether with the post context lines, it is unclear what the default\nbehaviour is for the command. It is not a new problem, but\nhopefully the remaining 3 patches I haven't read would address it?\n\nLet's keep reading.\n\nThanks.\n"},{"id":"518521","messageId":"xmqqbjrnhz6k.fsf@gitster.g","threadId":"63486","inReplyTo":"f3f54a3537f71d8d4e3755d93ce58cf6472a2b7a.1747763769.git.code@khaugsbakk.name","subject":"Re: [PATCH 4/6] doc: notes: mention comment character configuration","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-05-20T19:14:43Z","receivedAt":"2025-05-20T19:14:46Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"kristofferhaugsbakk@fastmail.com writes:\n\n> From: Kristoffer Haugsbakk \n>\n> Signed-off-by: Kristoffer Haugsbakk \n> ---\n> Documentation/git-notes.adoc | 5 ++++-\n> 1 file changed, 4 insertions(+), 1 deletion(-)\n>\n> diff --git a/Documentation/git-notes.adoc b/Documentation/git-notes.adoc\n> index 8706b33f2ee..1b714eb9e81 100644\n> --- a/Documentation/git-notes.adoc\n> +++ b/Documentation/git-notes.adoc\n> @@ -186,9 +186,12 @@ OPTIONS\n> `--no-stripspace`::\n> \tStrip leading and trailing whitespace from the note message.\n> \tAlso strip out empty lines other than a single line between\n> -\tparagraphs. Lines starting with `#` will be stripped out\n> +\tparagraphs. Lines starting with the comment character\n> +\t(default `#`) will be stripped out\n> \tin non-editor cases like `-m`, `-F` and `-C`, but not in\n> \teditor case like `git notes edit`, `-c`, etc.\n> ++\n> +See `core.commentChar` in linkgit:git-config[1].\n> \n> `--ref `::\n> \tManipulate the notes tree in __. This overrides\n\nThe above is more like [1/6] I commented on, rather than [2/6], so\nthe same comment \"why is it suggested that I go read about that\nvariable?\" applies. Perhaps\n\n ... starting with the comment character (the `core.commentChar`\n configuration variable, if set, otherwise `#`) will be ...\n\nor something? I dunno.\n\n"},{"id":"518522","messageId":"xmqq7c2bhz5d.fsf@gitster.g","threadId":"63486","inReplyTo":"cbb177479cae24b85284d507beff4b7abe173dc8.1747763769.git.code@khaugsbakk.name","subject":"Re: [PATCH 5/6] doc: notes: point out copy --stdin use with argv","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-05-20T19:15:26Z","receivedAt":"2025-05-20T19:15:29Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"kristofferhaugsbakk@fastmail.com writes:\n\n> From: Kristoffer Haugsbakk \n>\n> Unlike `remove --stdin`, this option cannot be combined with object\n> names given via the command line.\n>\n> Signed-off-by: Kristoffer Haugsbakk \n> ---\n> Documentation/git-notes.adoc | 3 +++\n> 1 file changed, 3 insertions(+)\n\nOK.\n\n> diff --git a/Documentation/git-notes.adoc b/Documentation/git-notes.adoc\n> index 1b714eb9e81..d2d7dac8d41 100644\n> --- a/Documentation/git-notes.adoc\n> +++ b/Documentation/git-notes.adoc\n> @@ -87,6 +87,9 @@ In `--stdin` mode, take lines in the format\n> on standard input, and copy the notes from each __ to its\n> corresponding __. (The optional __ is ignored so that\n> the command can read the input given to the `post-rewrite` hook.)\n> ++\n> +`--stdin` cannot be combined with object names given on the command\n> +line.\n> \n> `append`::\n> \tAppend new message(s) given by `-m` or `-F` options to an\n"},{"id":"518524","messageId":"xmqq34czhyz8.fsf@gitster.g","threadId":"63486","inReplyTo":"68e5eb78040419ba64e256910501c7e37194b222.1747763769.git.code@khaugsbakk.name","subject":"Re: [PATCH 6/6] doc: notes: treat --stdin equally between copy/remove","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-05-20T19:19:07Z","receivedAt":"2025-05-20T19:19:11Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"kristofferhaugsbakk@fastmail.com writes:\n\n> From: Kristoffer Haugsbakk \n>\n> 46538012d94 (notes remove: --stdin reads from the standard input,\n> 2011-05-18) added `--stdin` for the `remove` subcommand, documenting it\n> in the “Options” section. But `copy --stdin` was added before that, in\n> 160baa0d9cb (notes: implement 'git notes copy --stdin', 2010-03-12).\n>\n> Treat this option equally between the two subcommands:\n>\n> • remove: mention `--stdin` on the subcommand as well, like for `copy`\n> • copy: mention it as well under the option documentation\n>\n> Signed-off-by: Kristoffer Haugsbakk \n> ---\n> Documentation/git-notes.adoc | 10 +++++++---\n> 1 file changed, 7 insertions(+), 3 deletions(-)\n>\n> diff --git a/Documentation/git-notes.adoc b/Documentation/git-notes.adoc\n> index d2d7dac8d41..1542850eaaa 100644\n> --- a/Documentation/git-notes.adoc\n> +++ b/Documentation/git-notes.adoc\n> @@ -127,6 +127,10 @@ When done, the user can either finalize the merge with\n> \tgiving zero or one object from the command line, this is\n> \tequivalent to specifying an empty note message to\n> \tthe `edit` subcommand.\n> ++\n> +In `--stdin` mode, also remove the object names given on standard\n> +input. In other words, `--stdin` can be combined with object names from\n> +the command line.\n> \n> `prune`::\n> \tRemove all notes for non-existing/unreachable objects.\n> @@ -208,9 +212,9 @@ See `core.commentChar` in linkgit:git-config[1].\n> \tobject that does not have notes attached to it.\n> \n> `--stdin`::\n> -\tAlso read the object names to remove notes from the standard\n> -\tinput (there is no reason you cannot combine this with object\n> -\tnames from the command line).\n\nThe original was really bad, especially if it ignored the fact that\nthe 'copy' action also took the option.\n\n> +\tFor `remove` and `copy`. See the respective subcommands. This\n> +\toption can be combined with object names given via the command\n> +\tline for `remove`. However, this is not the case for `copy`.\n\nDuring my first read of this paragraph, I somehow read the first two\nsentences as \"if you want to learn how this option behaves with the\nremove and copy subcommands, go read the documentation for these\nsubcommands\", making me anticipate that the remainder of the\nparagraph would talks about what happens when --stdin is given to\nother subcommands. Apparently that is not what is going on.\n\nIt may be simpler to just say\n\n\tOnly valid for `remove` and `copy`. See the respective\n\tsubcommands.\n\nand stop there.\n\n"},{"id":"518564","messageId":"xmqqsekyds2e.fsf@gitster.g","threadId":"63486","inReplyTo":"xmqqfrgzhzbp.fsf@gitster.g","subject":"Re: [PATCH 3/6] doc: notes: split out options with negations","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-05-21T13:14:17Z","receivedAt":"2025-05-21T13:14:21Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Junio C Hamano writes:\n\n> kristofferhaugsbakk@fastmail.com writes:\n>\n>> -`--[no-]separator`::\n>> `--separator=`::\n>> +`--separator`::\n>> +`--no-separator`::\n>> \tSpecify a string used as a custom inter-paragraph separator\n>> \t(a newline is added at the end as needed). If `--no-separator`, no\n>> \tseparators will be added between paragraphs. Defaults to a blank\n>> \tline.\n>\n> OK.\n>\n>> -`--[no-]stripspace`::\n>> +`--stripspace`::\n>> +`--no-stripspace`::\n>> \tStrip leading and trailing whitespace from the note message.\n>> \tAlso strip out empty lines other than a single line between\n>> \tparagraphs. Lines starting with `#` will be stripped out\n>\n> Together with the post context lines, it is unclear what the default\n> behaviour is for the command. It is not a new problem, but\n> hopefully the remaining 3 patches I haven't read would address it?\n\nI guess this was left unresolved after the series, but it is\nperfectly fine to leave it outside the topic. Somebody else may\nwant to look into how exactly stripspace behaviour works by default\nand how this option affects [*] and document it here.\n\n[Footnote]\n\n * IIRC, we made the default to strip, unless the message came from\n an existing note in which case it is left intact; but whoever\n does the documentation update should check it.\n"},{"id":"518568","messageId":"CALnO6CAMgA1H3_Q+H6WRchMo4L2j_Qu8fdT4JVnfXyHwu97enQ@mail.gmail.com","threadId":"63486","inReplyTo":"68e5eb78040419ba64e256910501c7e37194b222.1747763769.git.code@khaugsbakk.name","subject":"Re: [PATCH 6/6] doc: notes: treat --stdin equally between copy/remove","fromName":"D. Ben Knoble","fromEmail":"ben.knoble@gmail.com","sentAt":"2025-05-21T13:19:31Z","receivedAt":"2025-05-21T13:19:47Z","isPatch":true,"sender":{"key":"ben.knoble@gmail.com","avatar":"https://avatars.githubusercontent.com/u/22802209?v=4"},"body":"On Tue, May 20, 2025 at 1:58 PM wrote:\n>\n> From: Kristoffer Haugsbakk \n>\n> 46538012d94 (notes remove: --stdin reads from the standard input,\n> 2011-05-18) added `--stdin` for the `remove` subcommand, documenting it\n> in the “Options” section. But `copy --stdin` was added before that, in\n> 160baa0d9cb (notes: implement 'git notes copy --stdin', 2010-03-12).\n>\n> Treat this option equally between the two subcommands:\n>\n> • remove: mention `--stdin` on the subcommand as well, like for `copy`\n> • copy: mention it as well under the option documentation\n\nOoh, bullet characters. I haven't seen anything quite like that in a\ncommit message in my short time watching the list. Neat!\n\n-- \nD. Ben Knoble\n"},{"id":"518578","messageId":"d4491de5-9482-4bd1-9fca-dd960a815f51@app.fastmail.com","threadId":"63486","inReplyTo":"xmqqsekyds2e.fsf@gitster.g","subject":"Re: [PATCH 3/6] doc: notes: split out options with negations","fromName":"Kristoffer Haugsbakk","fromEmail":"code@khaugsbakk.name","sentAt":"2025-05-21T14:42:15Z","receivedAt":"2025-05-21T14:43:23Z","isPatch":true,"sender":{"key":"code@khaugsbakk.name","avatar":"https://avatars.githubusercontent.com/u/2229597?v=4"},"body":"On Wed, May 21, 2025, at 15:14, Junio C Hamano wrote:\n>> Together with the post context lines, it is unclear what the default\n>> behaviour is for the command. It is not a new problem, but\n>> hopefully the remaining 3 patches I haven't read would address it?\n>\n> I guess this was left unresolved after the series, but it is\n> perfectly fine to leave it outside the topic. Somebody else may\n> want to look into how exactly stripspace behaviour works by default\n> and how this option affects [*] and document it here.\n>\n> [Footnote]\n>\n> * IIRC, we made the default to strip, unless the message came from\n> an existing note in which case it is left intact; but whoever\n> does the documentation update should check it.\n\nGood point. I looked over the options for any ambiguity but missed this\none.\n\nI’ll fix it on a separate patch in the next version.\n\n-- \nKristoffer\n"},{"id":"518579","messageId":"a9768fbd-7b94-4eb5-9906-0445c93be1d9@app.fastmail.com","threadId":"63486","inReplyTo":"CALnO6CAMgA1H3_Q+H6WRchMo4L2j_Qu8fdT4JVnfXyHwu97enQ@mail.gmail.com","subject":"Re: [PATCH 6/6] doc: notes: treat --stdin equally between copy/remove","fromName":"Kristoffer Haugsbakk","fromEmail":"code@khaugsbakk.name","sentAt":"2025-05-21T14:44:03Z","receivedAt":"2025-05-21T14:44:26Z","isPatch":true,"sender":{"key":"code@khaugsbakk.name","avatar":"https://avatars.githubusercontent.com/u/2229597?v=4"},"body":"On Wed, May 21, 2025, at 15:19, D. Ben Knoble wrote:\n> On Tue, May 20, 2025 at 1:58 PM wrote:\n>> • remove: mention `--stdin` on the subcommand as well, like for `copy`\n>> • copy: mention it as well under the option documentation\n>\n> Ooh, bullet characters. I haven't seen anything quite like that in a\n> commit message in my short time watching the list. Neat!\n\nThey get through the reviews somehow. ;)\n"},{"id":"518581","messageId":"8ddf10d7-d666-4298-8319-7feba1af85a1@app.fastmail.com","threadId":"63486","inReplyTo":"xmqq34czhyz8.fsf@gitster.g","subject":"Re: [PATCH 6/6] doc: notes: treat --stdin equally between copy/remove","fromName":"Kristoffer Haugsbakk","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2025-05-21T14:49:10Z","receivedAt":"2025-05-21T14:49:31Z","isPatch":true,"sender":{"key":"kristofferhaugsbakk@fastmail.com","avatar":null},"body":"On Tue, May 20, 2025, at 21:19, Junio C Hamano wrote:\n>> +\tFor `remove` and `copy`. See the respective subcommands. This\n>> +\toption can be combined with object names given via the command\n>> +\tline for `remove`. However, this is not the case for `copy`.\n>\n> During my first read of this paragraph, I somehow read the first two\n> sentences as \"if you want to learn how this option behaves with the\n> remove and copy subcommands, go read the documentation for these\n> subcommands\", making me anticipate that the remainder of the\n> paragraph would talks about what happens when --stdin is given to\n> other subcommands. Apparently that is not what is going on.\n>\n> It may be simpler to just say\n>\n> \tOnly valid for `remove` and `copy`. See the respective\n> \tsubcommands.\n>\n> and stop there.\n\nYep I agree. Just leave it to the subcommand sections.\n\n-- \nKristoffer Haugsbakk\n\n"},{"id":"518586","messageId":"817a28ae-b7dc-44ce-9ae4-2527081745da@app.fastmail.com","threadId":"63486","inReplyTo":"xmqqjz6bhzkm.fsf@gitster.g","subject":"Re: [PATCH 1/6] doc: stripspace: mention where the default comes from","fromName":"Kristoffer Haugsbakk","fromEmail":"code@khaugsbakk.name","sentAt":"2025-05-21T15:04:37Z","receivedAt":"2025-05-21T15:04:59Z","isPatch":true,"sender":{"key":"code@khaugsbakk.name","avatar":"https://avatars.githubusercontent.com/u/2229597?v=4"},"body":"On Tue, May 20, 2025, at 21:06, Junio C Hamano wrote:\n>> diff --git a/Documentation/git-stripspace.adoc b/Documentation/git-stripspace.adoc\n>> index a293327581a..1132a4cf9a9 100644\n>> --- a/Documentation/git-stripspace.adoc\n>> +++ b/Documentation/git-stripspace.adoc\n>> @@ -37,7 +37,8 @@ OPTIONS\n>> -------\n>> -s::\n>> --strip-comments::\n>> -\tSkip and remove all lines starting with a comment character (default '#').\n>> +\tSkip and remove all lines starting with a comment character (default `#`).\n>> +\tSee `core.commentChar` in linkgit:git-config[1].\n>\n> I've seen this kind of thing treat the configuration as the first\n> level default, with the hardcoded value as a fallback, i.e. spelling\n> it more like this:\n>\n> ... a comment character. Defaults to `core.commentChar`, which\n> in turn defaults to `#`.\n>\n> The way you phrased is syntactically easier to parse, but to some\n> readers, the readon why they are encouraged to learn about the\n> `core.commentChar` configuration may not be immediately obvious, so\n> I dunno.\n>\n> Thanks.\n\nI’m fine with that too. I ended up with this version because I tried to\navoid complex sentences. But it’s best to avoid a new paragraph.\n\nAnother alternative:\n\n a comment character (`core.commentChar`, default `#`)\n\nAnd the linkgit to git-config(1) is probably not needed on this kind\nof doc.\n\n-- \nKristoffer\n"},{"id":"518594","messageId":"xmqqwmaaartw.fsf@gitster.g","threadId":"63486","inReplyTo":"d4491de5-9482-4bd1-9fca-dd960a815f51@app.fastmail.com","subject":"Re: [PATCH 3/6] doc: notes: split out options with negations","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-05-21T15:47:39Z","receivedAt":"2025-05-21T15:47:43Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Kristoffer Haugsbakk\" writes:\n\n>> I guess this was left unresolved after the series, but it is\n>> perfectly fine to leave it outside the topic. Somebody else may\n>> want to look into how exactly stripspace behaviour works by default\n>> and how this option affects [*] and document it here.\n>>\n>> [Footnote]\n>>\n>> * IIRC, we made the default to strip, unless the message came from\n>> an existing note in which case it is left intact; but whoever\n>> does the documentation update should check it.\n>\n> Good point. I looked over the options for any ambiguity but missed this\n> one.\n\nHeh, that was one of the things the article you cited stressed on [*].\n\n> I’ll fix it on a separate patch in the next version.\n\nThanks.\n\n\n[Reference]\n\n* https://lore.kernel.org/git/xmqqcyct1mtq.fsf@gitster.g/\n"},{"id":"518595","messageId":"xmqqsekyarp8.fsf@gitster.g","threadId":"63486","inReplyTo":"a9768fbd-7b94-4eb5-9906-0445c93be1d9@app.fastmail.com","subject":"Re: [PATCH 6/6] doc: notes: treat --stdin equally between copy/remove","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-05-21T15:50:27Z","receivedAt":"2025-05-21T15:50:30Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Kristoffer Haugsbakk\" writes:\n\n> On Wed, May 21, 2025, at 15:19, D. Ben Knoble wrote:\n>> On Tue, May 20, 2025 at 1:58 PM wrote:\n>>> • remove: mention `--stdin` on the subcommand as well, like for `copy`\n>>> • copy: mention it as well under the option documentation\n>>\n>> Ooh, bullet characters. I haven't seen anything quite like that in a\n>> commit message in my short time watching the list. Neat!\n>\n> They get through the reviews somehow. ;)\n\nThe \"downside\" may be that they may inconvenience folks still living\nin ASCII-only world, but I suspect it is rather hard to find\nASCII-only terminals that render not-so-uncommon Unicode characters\nas garbage, so perhaps there is no longer any such downside?\n"},{"id":"518596","messageId":"accfdb7c-c31b-460c-b720-df0d1ee210ff@app.fastmail.com","threadId":"63486","inReplyTo":"xmqqwmaaartw.fsf@gitster.g","subject":"Re: [PATCH 3/6] doc: notes: split out options with negations","fromName":"Kristoffer Haugsbakk","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2025-05-21T15:52:32Z","receivedAt":"2025-05-21T15:52:53Z","isPatch":true,"sender":{"key":"kristofferhaugsbakk@fastmail.com","avatar":null},"body":"On Wed, May 21, 2025, at 17:47, Junio C Hamano wrote:\n> Heh, that was one of the things the article you cited stressed on [*].\n\nI promise that part was fresh in my mind at that point. But apparently \nthe mind itself was not that fresh.\n\n-- \nKristoffer\n"},{"id":"518788","messageId":"cover.1748028010.git.code@khaugsbakk.name","threadId":"63486","inReplyTo":"cover.1747763769.git.code@khaugsbakk.name","subject":"[PATCH v2 0/9] doc: --stdin on notes and core.commentChar mentions","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2025-05-23T19:29:46Z","receivedAt":"2025-05-23T19:31:51Z","isPatch":true,"sender":{"key":"kristofferhaugsbakk@fastmail.com","avatar":null},"body":"From: Kristoffer Haugsbakk \n\nI wanted to fix `--stdin` in the git-notes(1) documentation. Then I\nfound some other things on that doc as well as things to do with\n`core.commentChar`.\n\n§ Changes v2\n\nAddress the feedback on v1.\n\nI discovered that patch “doc: notes: mention comment character\nconfiguration” was misguided since\n\n1. Mentioning the comment character isn’t really relevant anywhere\n2. The text conflates `--[no-]stripspace` with handling comment lines,\n which is wrong\n\nThat patch is replaced with patches 4 and 5.\n\nSee the notes on the patches for details.\n\nKristoffer Haugsbakk (9):\n doc: stripspace: mention where the default comes from\n doc: config: mention core.commentChar on commit.cleanup\n doc: notes: split out options with negated forms\n doc: notes: rework --[no-]stripspace\n doc: notes: remove stripspace discussion from other options\n doc: notes: clearly state that --stripspace is the default\n doc: notes: point out copy --stdin use with argv\n doc: notes: treat --stdin equally between copy/remove\n doc: notes: use stuck form throughout\n\n Documentation/config/commit.adoc | 7 +++--\n Documentation/git-notes.adoc | 51 ++++++++++++++++++-------------\n Documentation/git-stripspace.adoc | 3 +-\n 3 files changed, 36 insertions(+), 25 deletions(-)\n\nInterdiff against v1:\ndiff --git a/Documentation/git-notes.adoc b/Documentation/git-notes.adoc\nindex 1542850eaaa..43436daeccc 100644\n--- a/Documentation/git-notes.adoc\n+++ b/Documentation/git-notes.adoc\n@@ -151,26 +151,18 @@ OPTIONS\n \tUse the given note message (instead of prompting).\n \tIf multiple `-m` options are given, their values\n \tare concatenated as separate paragraphs.\n-\tLines starting with `#` and empty lines other than a\n-\tsingle line between paragraphs will be stripped out.\n-\tIf you wish to keep them verbatim, use `--no-stripspace`.\n \n `-F `::\n `--file=`::\n \tTake the note message from the given file. Use `-` to\n \tread the note message from the standard input.\n-\tLines starting with `#` and empty lines other than a\n-\tsingle line between paragraphs will be stripped out.\n-\tIf you wish to keep them verbatim, use `--no-stripspace`.\n \n `-C `::\n `--reuse-message=`::\n \tTake the given blob object (for example, another note) as the\n \tnote message. (Use `git notes copy ` instead to\n-\tcopy notes between objects.). By default, message will be\n-\tcopied verbatim, but if you wish to strip out the lines\n-\tstarting with `#` and empty lines other than a single line\n-\tbetween paragraphs, use with `--stripspace` option.\n+\tcopy notes between objects.) Implies `--no-stripspace` since\n+\tthe default behavior is to copy the message verbatim.\n \n `-c `::\n `--reedit-message=`::\n@@ -191,16 +183,23 @@ OPTIONS\n \n `--stripspace`::\n `--no-stripspace`::\n-\tStrip leading and trailing whitespace from the note message.\n-\tAlso strip out empty lines other than a single line between\n-\tparagraphs. Lines starting with the comment character\n-\t(default `#`) will be stripped out\n-\tin non-editor cases like `-m`, `-F` and `-C`, but not in\n-\teditor case like `git notes edit`, `-c`, etc.\n+\tClean up whitespace. Specifically (see\n+\tlinkgit:git-stripspace[1]):\n +\n-See `core.commentChar` in linkgit:git-config[1].\n+--\n+- remove trailing whitespace from all lines\n+- collapse multiple consecutive empty lines into one empty line\n+- remove empty lines from the beginning and end of the input\n+- add a missing `\\n` to the last line if necessary.\n+--\n++\n+`--stripspace` is the default except for\n+`-C`/`--reuse-message`. However, keep in mind that this depends on the\n+order of similar options. For example, for `-C -m`,\n+`--stripspace` will be used because the default for `-m` overrides the\n+previous `-C`.\n \n-`--ref `::\n+`--ref=`::\n \tManipulate the notes tree in __. This overrides\n \t`GIT_NOTES_REF` and the `core.notesRef` configuration. The ref\n \tspecifies the full refname when it begins with `refs/notes/`; when it\n@@ -212,9 +211,7 @@ See `core.commentChar` in linkgit:git-config[1].\n \tobject that does not have notes attached to it.\n \n `--stdin`::\n-\tFor `remove` and `copy`. See the respective subcommands. This\n-\toption can be combined with object names given via the command\n-\tline for `remove`. However, this is not the case for `copy`.\n+\tFor `remove` and `copy`. See the respective subcommands.\n \n `-n`::\n `--dry-run`::\ndiff --git a/Documentation/git-stripspace.adoc b/Documentation/git-stripspace.adoc\nindex 1132a4cf9a9..37287f211f0 100644\n--- a/Documentation/git-stripspace.adoc\n+++ b/Documentation/git-stripspace.adoc\n@@ -37,8 +37,8 @@ OPTIONS\n -------\n -s::\n --strip-comments::\n-\tSkip and remove all lines starting with a comment character (default `#`).\n-\tSee `core.commentChar` in linkgit:git-config[1].\n+\tSkip and remove all lines starting with a comment character\n+\t(`core.commentChar`, default `#`).\n \n -c::\n --comment-lines::\nRange-diff against v1:\n -: ----------- > 1: bf3ea7f23c0 doc: stripspace: mention where the default comes from\n 2: b43b78aba63 = 2: e9cf956a824 doc: config: mention core.commentChar on commit.cleanup\n 3: d2b6864b707 ! 3: 14dc58120e3 doc: notes: split out options with negations\n @@ Metadata\n Author: Kristoffer Haugsbakk \n \n ## Commit message ##\n - doc: notes: split out options with negations\n + doc: notes: split out options with negated forms\n \n Split these out so that they are easier to search for.[1]\n \n @@ Commit message\n \n Signed-off-by: Kristoffer Haugsbakk \n \n +\n + ## Notes (series) ##\n + v2:\n + • Message: Use “negated form” since that seems more typical\n +\n ## Documentation/git-notes.adoc ##\n @@ Documentation/git-notes.adoc: OPTIONS\n \tAllow an empty note object to be stored. The default behavior is\n 4: f3f54a3537f ! 4: c68a91f81ba doc: notes: mention comment character configuration\n @@ Metadata\n Author: Kristoffer Haugsbakk \n \n ## Commit message ##\n - doc: notes: mention comment character configuration\n + doc: notes: rework --[no-]stripspace\n +\n + Document this option by copying the bullet list from git-stripspace(1).\n + A bullet list is cleaner when there are this many points to consider.\n + We also get a more standardized description of the multiple-blank-lines\n + behavior. Compare the repeating (git-notes(1)):\n +\n + empty lines other than a single line between paragraphs\n +\n + With (git-stripspace(1)):\n +\n + multiple consecutive empty lines\n +\n + And:\n +\n + leading [...] whitespace\n +\n + With:\n +\n + empty lines from the beginning\n +\n + Leading whitespace in the form of spaces (indentation) are not removed.\n + However, empty lines at the start of the message are removed.\n +\n + Note that we drop the mentions of comment line handling because they are\n + wrong; this option does not control how lines which can be recognized as\n + comment lines are handled. Only interactivity controls that:\n +\n + • Comment lines are stripped after editing interactively\n + • Lines which could be recognized as comment lines are left alone when\n + the message is given non-interactively\n +\n + So it is misleading to document the comment line behavior on\n + this option.\n +\n + Further, the text is wrong:\n +\n + Lines starting with `#` will be stripped out in non-editor cases\n + like `-m`, [...]\n +\n + Comment lines are still indirectly discussed on other options. We will\n + deal with them in the next commit.\n \n Signed-off-by: Kristoffer Haugsbakk \n \n +\n + ## Notes (series) ##\n + v2:\n + • New\n + • Together with one other other patch replaces v1 patch “doc: notes:\n + mention comment character configuration”\n + • I figured out that mentioning the comment character/comment lines\n + doesn’t make sense here. So all attempts to rephrase “comment\n + character” or “lines that start with `#`” are gone\n +\n ## Documentation/git-notes.adoc ##\n @@ Documentation/git-notes.adoc: OPTIONS\n + \n + `--stripspace`::\n `--no-stripspace`::\n - \tStrip leading and trailing whitespace from the note message.\n - \tAlso strip out empty lines other than a single line between\n +-\tStrip leading and trailing whitespace from the note message.\n +-\tAlso strip out empty lines other than a single line between\n -\tparagraphs. Lines starting with `#` will be stripped out\n -+\tparagraphs. Lines starting with the comment character\n -+\t(default `#`) will be stripped out\n - \tin non-editor cases like `-m`, `-F` and `-C`, but not in\n - \teditor case like `git notes edit`, `-c`, etc.\n +-\tin non-editor cases like `-m`, `-F` and `-C`, but not in\n +-\teditor case like `git notes edit`, `-c`, etc.\n ++\tClean up whitespace. Specifically (see\n ++\tlinkgit:git-stripspace[1]):\n ++\n -+See `core.commentChar` in linkgit:git-config[1].\n ++- remove trailing whitespace from all lines\n ++- collapse multiple consecutive empty lines into one empty line\n ++- remove empty lines from the beginning and end of the input\n ++- add a missing `\\n` to the last line if necessary.\n \n `--ref `::\n \tManipulate the notes tree in __. This overrides\n 1: 630ef019786 ! 5: f4755040f38 doc: stripspace: mention where the default comes from\n @@ Metadata\n Author: Kristoffer Haugsbakk \n \n ## Commit message ##\n - doc: stripspace: mention where the default comes from\n + doc: notes: remove stripspace discussion from other options\n \n - Also quote `#` in line with the modern formatting convention.\n + Cleaning up whitespace in metadata is typical porcelain behavior and\n + this default does not need to be pointed out.[1] Only speak up when\n + the default `--stripspace` is not used.\n +\n + Also remove all misleading mentions of comment lines in the process;\n + see the previous commit.\n +\n + Also remove the period that trails the parenthetical here.\n +\n + † 1: See `-F` in git-commit(1) which has nothing to say about whitespace\n + cleanup. The cleanup discussion is on `--cleanup`.\n \n Signed-off-by: Kristoffer Haugsbakk \n \n \n ## Notes (series) ##\n - “modern formatting convention”\n -\n - It looks like characters are quoted with backticks in the commits I’ve\n - seen by Jean-Noël Avila lately.\n -\n - ## Documentation/git-stripspace.adoc ##\n -@@ Documentation/git-stripspace.adoc: OPTIONS\n - -------\n - -s::\n - --strip-comments::\n --\tSkip and remove all lines starting with a comment character (default '#').\n -+\tSkip and remove all lines starting with a comment character (default `#`).\n -+\tSee `core.commentChar` in linkgit:git-config[1].\n + v2:\n + • New\n + • Together with one other patch replaces v1 patch “doc: notes:\n + mention comment character configuration”\n + • I figured out that mentioning the comment character/comment lines\n + doesn’t make sense here. So all attempts to rephrase “comment\n + character” or “lines that start with `#`” are gone\n +\n + ## Documentation/git-notes.adoc ##\n +@@ Documentation/git-notes.adoc: OPTIONS\n + \tUse the given note message (instead of prompting).\n + \tIf multiple `-m` options are given, their values\n + \tare concatenated as separate paragraphs.\n +-\tLines starting with `#` and empty lines other than a\n +-\tsingle line between paragraphs will be stripped out.\n +-\tIf you wish to keep them verbatim, use `--no-stripspace`.\n + \n + `-F `::\n + `--file=`::\n + \tTake the note message from the given file. Use `-` to\n + \tread the note message from the standard input.\n +-\tLines starting with `#` and empty lines other than a\n +-\tsingle line between paragraphs will be stripped out.\n +-\tIf you wish to keep them verbatim, use `--no-stripspace`.\n + \n + `-C `::\n + `--reuse-message=`::\n + \tTake the given blob object (for example, another note) as the\n + \tnote message. (Use `git notes copy ` instead to\n +-\tcopy notes between objects.). By default, message will be\n +-\tcopied verbatim, but if you wish to strip out the lines\n +-\tstarting with `#` and empty lines other than a single line\n +-\tbetween paragraphs, use with `--stripspace` option.\n ++\tcopy notes between objects.) Implies `--no-stripspace` since\n ++\tthe default behavior is to copy the message verbatim.\n \n - -c::\n - --comment-lines::\n + `-c `::\n + `--reedit-message=`::\n -: ----------- > 6: be89c3349d2 doc: notes: clearly state that --stripspace is the default\n 5: cbb177479ca = 7: d8a22847a7d doc: notes: point out copy --stdin use with argv\n 6: 68e5eb78040 ! 8: 3e8ecf1b668 doc: notes: treat --stdin equally between copy/remove\n @@ Commit message\n \n Signed-off-by: Kristoffer Haugsbakk \n \n +\n + ## Notes (series) ##\n + v2:\n + • On --stdin: just refer to the respective subcommands and stop there.\n + As suggested.\n +\n + Link: https://lore.kernel.org/git/xmqq34czhyz8.fsf@gitster.g/\n +\n ## Documentation/git-notes.adoc ##\n @@ Documentation/git-notes.adoc: When done, the user can either finalize the merge with\n \tgiving zero or one object from the command line, this is\n @@ Documentation/git-notes.adoc: When done, the user can either finalize the merge\n \n `prune`::\n \tRemove all notes for non-existing/unreachable objects.\n -@@ Documentation/git-notes.adoc: See `core.commentChar` in linkgit:git-config[1].\n +@@ Documentation/git-notes.adoc: previous `-C`.\n \tobject that does not have notes attached to it.\n \n `--stdin`::\n -\tAlso read the object names to remove notes from the standard\n -\tinput (there is no reason you cannot combine this with object\n -\tnames from the command line).\n -+\tFor `remove` and `copy`. See the respective subcommands. This\n -+\toption can be combined with object names given via the command\n -+\tline for `remove`. However, this is not the case for `copy`.\n ++\tFor `remove` and `copy`. See the respective subcommands.\n \n `-n`::\n `--dry-run`::\n -: ----------- > 9: 73bdcaecae5 doc: notes: use stuck form throughout\n\nbase-commit: cb96e1697ad6e54d11fc920c95f82977f8e438f8\n-- \n2.49.0.780.g892193c3f50\n\n"},{"id":"518789","messageId":"bf3ea7f23c08b5c477fedd42e2a0e518607c8ec6.1748028010.git.code@khaugsbakk.name","threadId":"63486","inReplyTo":"cover.1748028010.git.code@khaugsbakk.name","subject":"[PATCH v2 1/9] doc: stripspace: mention where the default comes from","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2025-05-23T19:29:47Z","receivedAt":"2025-05-23T19:31:53Z","isPatch":true,"sender":{"key":"kristofferhaugsbakk@fastmail.com","avatar":null},"body":"From: Kristoffer Haugsbakk \n\nAlso quote `#` in line with the modern formatting convention.\n\nSigned-off-by: Kristoffer Haugsbakk \n---\n\nNotes (series):\n v2:\n • More terse mention of the default as well as the configuration\n variable. Don’t link to git-config(1), there’s no real need.\n \n Link: https://lore.kernel.org/git/xmqqjz6bhzkm.fsf@gitster.g/\n v1:\n • “modern formatting convention”\n \n It looks like characters are quoted with backticks in the commits I’ve\n seen by Jean-Noël Avila lately.\n\n Documentation/git-stripspace.adoc | 3 ++-\n 1 file changed, 2 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/git-stripspace.adoc b/Documentation/git-stripspace.adoc\nindex a293327581a..37287f211f0 100644\n--- a/Documentation/git-stripspace.adoc\n+++ b/Documentation/git-stripspace.adoc\n@@ -37,7 +37,8 @@ OPTIONS\n -------\n -s::\n --strip-comments::\n-\tSkip and remove all lines starting with a comment character (default '#').\n+\tSkip and remove all lines starting with a comment character\n+\t(`core.commentChar`, default `#`).\n \n -c::\n --comment-lines::\n-- \n2.49.0.780.g892193c3f50\n\n"},{"id":"518790","messageId":"e9cf956a824c888b7313d6a2ff5c513374b3e40e.1748028010.git.code@khaugsbakk.name","threadId":"63486","inReplyTo":"cover.1748028010.git.code@khaugsbakk.name","subject":"[PATCH v2 2/9] doc: config: mention core.commentChar on commit.cleanup","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2025-05-23T19:29:48Z","receivedAt":"2025-05-23T19:31:56Z","isPatch":true,"sender":{"key":"kristofferhaugsbakk@fastmail.com","avatar":null},"body":"From: Kristoffer Haugsbakk \n\nMention it in parentheses since we are in a configuration context.\nRefer to the default as such, not as “the” character.\n\nAlso don’t mention `#` again; just say “comment character”.\n\nSigned-off-by: Kristoffer Haugsbakk \n---\n Documentation/config/commit.adoc | 7 ++++---\n 1 file changed, 4 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/config/commit.adoc b/Documentation/config/commit.adoc\nindex d3f4624fd27..208ae76c816 100644\n--- a/Documentation/config/commit.adoc\n+++ b/Documentation/config/commit.adoc\n@@ -8,10 +8,11 @@ endif::git-commit[]\n \tThis setting overrides the default of the `--cleanup` option in\n \t`git commit`. {see-git-commit} Changing the default can be useful\n \twhen you always want to keep lines that begin\n-\twith the comment character `#` in your log message, in which case you\n+\twith the comment character (`core.commentChar`, default `#`)\n+\tin your log message, in which case you\n \twould do `git config commit.cleanup whitespace` (note that you will\n-\thave to remove the help lines that begin with `#` in the commit log\n-\ttemplate yourself, if you do this).\n+\thave to remove the help lines that begin with the comment character\n+\tin the commit log template yourself, if you do this).\n \n `commit.gpgSign`::\n \tA boolean to specify whether all commits should be GPG signed.\n-- \n2.49.0.780.g892193c3f50\n\n"},{"id":"518791","messageId":"14dc58120e3da564e28e1b442d481d632c28aeab.1748028010.git.code@khaugsbakk.name","threadId":"63486","inReplyTo":"cover.1748028010.git.code@khaugsbakk.name","subject":"[PATCH v2 3/9] doc: notes: split out options with negated forms","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2025-05-23T19:29:49Z","receivedAt":"2025-05-23T19:32:00Z","isPatch":true,"sender":{"key":"kristofferhaugsbakk@fastmail.com","avatar":null},"body":"From: Kristoffer Haugsbakk \n\nSplit these out so that they are easier to search for.[1]\n\n[1]: https://lore.kernel.org/git/xmqqcyct1mtq.fsf@gitster.g/\n\nSigned-off-by: Kristoffer Haugsbakk \n---\n\nNotes (series):\n v2:\n • Message: Use “negated form” since that seems more typical\n\n Documentation/git-notes.adoc | 6 ++++--\n 1 file changed, 4 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/git-notes.adoc b/Documentation/git-notes.adoc\nindex bcfe3dacd3f..8706b33f2ee 100644\n--- a/Documentation/git-notes.adoc\n+++ b/Documentation/git-notes.adoc\n@@ -174,14 +174,16 @@ OPTIONS\n \tAllow an empty note object to be stored. The default behavior is\n \tto automatically remove empty notes.\n \n-`--[no-]separator`::\n `--separator=`::\n+`--separator`::\n+`--no-separator`::\n \tSpecify a string used as a custom inter-paragraph separator\n \t(a newline is added at the end as needed). If `--no-separator`, no\n \tseparators will be added between paragraphs. Defaults to a blank\n \tline.\n \n-`--[no-]stripspace`::\n+`--stripspace`::\n+`--no-stripspace`::\n \tStrip leading and trailing whitespace from the note message.\n \tAlso strip out empty lines other than a single line between\n \tparagraphs. Lines starting with `#` will be stripped out\n-- \n2.49.0.780.g892193c3f50\n\n"},{"id":"518792","messageId":"c68a91f81ba180acb1025b229dee3d1e61691e75.1748028010.git.code@khaugsbakk.name","threadId":"63486","inReplyTo":"cover.1748028010.git.code@khaugsbakk.name","subject":"[PATCH v2 4/9] doc: notes: rework --[no-]stripspace","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2025-05-23T19:29:50Z","receivedAt":"2025-05-23T19:32:04Z","isPatch":true,"sender":{"key":"kristofferhaugsbakk@fastmail.com","avatar":null},"body":"From: Kristoffer Haugsbakk \n\nDocument this option by copying the bullet list from git-stripspace(1).\nA bullet list is cleaner when there are this many points to consider.\nWe also get a more standardized description of the multiple-blank-lines\nbehavior. Compare the repeating (git-notes(1)):\n\n empty lines other than a single line between paragraphs\n\nWith (git-stripspace(1)):\n\n multiple consecutive empty lines\n\nAnd:\n\n leading [...] whitespace\n\nWith:\n\n empty lines from the beginning\n\nLeading whitespace in the form of spaces (indentation) are not removed.\nHowever, empty lines at the start of the message are removed.\n\nNote that we drop the mentions of comment line handling because they are\nwrong; this option does not control how lines which can be recognized as\ncomment lines are handled. Only interactivity controls that:\n\n• Comment lines are stripped after editing interactively\n• Lines which could be recognized as comment lines are left alone when\n the message is given non-interactively\n\nSo it is misleading to document the comment line behavior on\nthis option.\n\nFurther, the text is wrong:\n\n Lines starting with `#` will be stripped out in non-editor cases\n like `-m`, [...]\n\nComment lines are still indirectly discussed on other options. We will\ndeal with them in the next commit.\n\nSigned-off-by: Kristoffer Haugsbakk \n---\n\nNotes (series):\n v2:\n • New\n • Together with one other other patch replaces v1 patch “doc: notes:\n mention comment character configuration”\n • I figured out that mentioning the comment character/comment lines\n doesn’t make sense here. So all attempts to rephrase “comment\n character” or “lines that start with `#`” are gone\n\n Documentation/git-notes.adoc | 12 +++++++-----\n 1 file changed, 7 insertions(+), 5 deletions(-)\n\ndiff --git a/Documentation/git-notes.adoc b/Documentation/git-notes.adoc\nindex 8706b33f2ee..d672794a942 100644\n--- a/Documentation/git-notes.adoc\n+++ b/Documentation/git-notes.adoc\n@@ -184,11 +184,13 @@ OPTIONS\n \n `--stripspace`::\n `--no-stripspace`::\n-\tStrip leading and trailing whitespace from the note message.\n-\tAlso strip out empty lines other than a single line between\n-\tparagraphs. Lines starting with `#` will be stripped out\n-\tin non-editor cases like `-m`, `-F` and `-C`, but not in\n-\teditor case like `git notes edit`, `-c`, etc.\n+\tClean up whitespace. Specifically (see\n+\tlinkgit:git-stripspace[1]):\n++\n+- remove trailing whitespace from all lines\n+- collapse multiple consecutive empty lines into one empty line\n+- remove empty lines from the beginning and end of the input\n+- add a missing `\\n` to the last line if necessary.\n \n `--ref `::\n \tManipulate the notes tree in __. This overrides\n-- \n2.49.0.780.g892193c3f50\n\n"},{"id":"518793","messageId":"f4755040f38170b508e9cba03a7226b5b4d5cd9c.1748028010.git.code@khaugsbakk.name","threadId":"63486","inReplyTo":"cover.1748028010.git.code@khaugsbakk.name","subject":"[PATCH v2 5/9] doc: notes: remove stripspace discussion from other options","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2025-05-23T19:29:51Z","receivedAt":"2025-05-23T19:32:07Z","isPatch":true,"sender":{"key":"kristofferhaugsbakk@fastmail.com","avatar":null},"body":"From: Kristoffer Haugsbakk \n\nCleaning up whitespace in metadata is typical porcelain behavior and\nthis default does not need to be pointed out.[1] Only speak up when\nthe default `--stripspace` is not used.\n\nAlso remove all misleading mentions of comment lines in the process;\nsee the previous commit.\n\nAlso remove the period that trails the parenthetical here.\n\n† 1: See `-F` in git-commit(1) which has nothing to say about whitespace\n cleanup. The cleanup discussion is on `--cleanup`.\n\nSigned-off-by: Kristoffer Haugsbakk \n---\n\nNotes (series):\n v2:\n • New\n • Together with one other patch replaces v1 patch “doc: notes:\n mention comment character configuration”\n • I figured out that mentioning the comment character/comment lines\n doesn’t make sense here. So all attempts to rephrase “comment\n character” or “lines that start with `#`” are gone\n\n Documentation/git-notes.adoc | 12 ++----------\n 1 file changed, 2 insertions(+), 10 deletions(-)\n\ndiff --git a/Documentation/git-notes.adoc b/Documentation/git-notes.adoc\nindex d672794a942..383e8bca685 100644\n--- a/Documentation/git-notes.adoc\n+++ b/Documentation/git-notes.adoc\n@@ -144,26 +144,18 @@ OPTIONS\n \tUse the given note message (instead of prompting).\n \tIf multiple `-m` options are given, their values\n \tare concatenated as separate paragraphs.\n-\tLines starting with `#` and empty lines other than a\n-\tsingle line between paragraphs will be stripped out.\n-\tIf you wish to keep them verbatim, use `--no-stripspace`.\n \n `-F `::\n `--file=`::\n \tTake the note message from the given file. Use `-` to\n \tread the note message from the standard input.\n-\tLines starting with `#` and empty lines other than a\n-\tsingle line between paragraphs will be stripped out.\n-\tIf you wish to keep them verbatim, use `--no-stripspace`.\n \n `-C `::\n `--reuse-message=`::\n \tTake the given blob object (for example, another note) as the\n \tnote message. (Use `git notes copy ` instead to\n-\tcopy notes between objects.). By default, message will be\n-\tcopied verbatim, but if you wish to strip out the lines\n-\tstarting with `#` and empty lines other than a single line\n-\tbetween paragraphs, use with `--stripspace` option.\n+\tcopy notes between objects.) Implies `--no-stripspace` since\n+\tthe default behavior is to copy the message verbatim.\n \n `-c `::\n `--reedit-message=`::\n-- \n2.49.0.780.g892193c3f50\n\n"},{"id":"518794","messageId":"be89c3349d24e47a38f04538d3d1e3730dfc37a9.1748028010.git.code@khaugsbakk.name","threadId":"63486","inReplyTo":"cover.1748028010.git.code@khaugsbakk.name","subject":"[PATCH v2 6/9] doc: notes: clearly state that --stripspace is the default","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2025-05-23T19:29:52Z","receivedAt":"2025-05-23T19:32:10Z","isPatch":true,"sender":{"key":"kristofferhaugsbakk@fastmail.com","avatar":null},"body":"From: Kristoffer Haugsbakk \n\nClearly state when which of the regular and negated form of the\noption take effect.[1]\n\n[1]: https://lore.kernel.org/git/xmqqcyct1mtq.fsf@gitster.g/\n\nSigned-off-by: Kristoffer Haugsbakk \n---\n\nNotes (series):\n v2:\n • New\n • The `--` are to prevent the new paragraph from becoming a continuation\n of the last bullet point\n • Junio pointed out that I didn’t go over the part about checking\n which variant (regular or negation) are the default. See the link:\n \n https://lore.kernel.org/git/xmqqcyct1mtq.fsf@gitster.g/\n \n I decided to do this on this series.\n \n Link: https://lore.kernel.org/git/xmqqfrgzhzbp.fsf@gitster.g/\n • The last part of the paragraph is based on the commit message of\n c4e2aa7d45f (notes.c: introduce \"--[no-]stripspace\" option,\n 2023-05-27).\n \n See the review on the patch:\n \n https://lore.kernel.org/git/xmqq4jp326oj.fsf@gitster.g/\n \n There was concern about the order of options:\n \n > ... One more thing need to note is \"the order of\n > the options matter\", [...]\n \n This sounds more like a design/implementation mistake that we may\n want to fix.\n \n This new part is supposed to address that.\n\n Documentation/git-notes.adoc | 8 ++++++++\n 1 file changed, 8 insertions(+)\n\ndiff --git a/Documentation/git-notes.adoc b/Documentation/git-notes.adoc\nindex 383e8bca685..bad83116329 100644\n--- a/Documentation/git-notes.adoc\n+++ b/Documentation/git-notes.adoc\n@@ -179,10 +179,18 @@ OPTIONS\n \tClean up whitespace. Specifically (see\n \tlinkgit:git-stripspace[1]):\n +\n+--\n - remove trailing whitespace from all lines\n - collapse multiple consecutive empty lines into one empty line\n - remove empty lines from the beginning and end of the input\n - add a missing `\\n` to the last line if necessary.\n+--\n++\n+`--stripspace` is the default except for\n+`-C`/`--reuse-message`. However, keep in mind that this depends on the\n+order of similar options. For example, for `-C -m`,\n+`--stripspace` will be used because the default for `-m` overrides the\n+previous `-C`.\n \n `--ref `::\n \tManipulate the notes tree in __. This overrides\n-- \n2.49.0.780.g892193c3f50\n\n"},{"id":"518795","messageId":"d8a22847a7df16a1a38eeeacaf714015c7c1a3c4.1748028010.git.code@khaugsbakk.name","threadId":"63486","inReplyTo":"cover.1748028010.git.code@khaugsbakk.name","subject":"[PATCH v2 7/9] doc: notes: point out copy --stdin use with argv","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2025-05-23T19:29:53Z","receivedAt":"2025-05-23T19:32:13Z","isPatch":true,"sender":{"key":"kristofferhaugsbakk@fastmail.com","avatar":null},"body":"From: Kristoffer Haugsbakk \n\nUnlike `remove --stdin`, this option cannot be combined with object\nnames given via the command line.\n\nSigned-off-by: Kristoffer Haugsbakk \n---\n Documentation/git-notes.adoc | 3 +++\n 1 file changed, 3 insertions(+)\n\ndiff --git a/Documentation/git-notes.adoc b/Documentation/git-notes.adoc\nindex bad83116329..ad152aa94ce 100644\n--- a/Documentation/git-notes.adoc\n+++ b/Documentation/git-notes.adoc\n@@ -87,6 +87,9 @@ In `--stdin` mode, take lines in the format\n on standard input, and copy the notes from each __ to its\n corresponding __. (The optional __ is ignored so that\n the command can read the input given to the `post-rewrite` hook.)\n++\n+`--stdin` cannot be combined with object names given on the command\n+line.\n \n `append`::\n \tAppend new message(s) given by `-m` or `-F` options to an\n-- \n2.49.0.780.g892193c3f50\n\n"},{"id":"518796","messageId":"3e8ecf1b668277988cc5d166586105d1d5018366.1748028010.git.code@khaugsbakk.name","threadId":"63486","inReplyTo":"cover.1748028010.git.code@khaugsbakk.name","subject":"[PATCH v2 8/9] doc: notes: treat --stdin equally between copy/remove","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2025-05-23T19:29:54Z","receivedAt":"2025-05-23T19:32:17Z","isPatch":true,"sender":{"key":"kristofferhaugsbakk@fastmail.com","avatar":null},"body":"From: Kristoffer Haugsbakk \n\n46538012d94 (notes remove: --stdin reads from the standard input,\n2011-05-18) added `--stdin` for the `remove` subcommand, documenting it\nin the “Options” section. But `copy --stdin` was added before that, in\n160baa0d9cb (notes: implement 'git notes copy --stdin', 2010-03-12).\n\nTreat this option equally between the two subcommands:\n\n• remove: mention `--stdin` on the subcommand as well, like for `copy`\n• copy: mention it as well under the option documentation\n\nSigned-off-by: Kristoffer Haugsbakk \n---\n\nNotes (series):\n v2:\n • On --stdin: just refer to the respective subcommands and stop there.\n As suggested.\n \n Link: https://lore.kernel.org/git/xmqq34czhyz8.fsf@gitster.g/\n\n Documentation/git-notes.adoc | 8 +++++---\n 1 file changed, 5 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/git-notes.adoc b/Documentation/git-notes.adoc\nindex ad152aa94ce..a0167af5aba 100644\n--- a/Documentation/git-notes.adoc\n+++ b/Documentation/git-notes.adoc\n@@ -127,6 +127,10 @@ When done, the user can either finalize the merge with\n \tgiving zero or one object from the command line, this is\n \tequivalent to specifying an empty note message to\n \tthe `edit` subcommand.\n++\n+In `--stdin` mode, also remove the object names given on standard\n+input. In other words, `--stdin` can be combined with object names from\n+the command line.\n \n `prune`::\n \tRemove all notes for non-existing/unreachable objects.\n@@ -207,9 +211,7 @@ previous `-C`.\n \tobject that does not have notes attached to it.\n \n `--stdin`::\n-\tAlso read the object names to remove notes from the standard\n-\tinput (there is no reason you cannot combine this with object\n-\tnames from the command line).\n+\tFor `remove` and `copy`. See the respective subcommands.\n \n `-n`::\n `--dry-run`::\n-- \n2.49.0.780.g892193c3f50\n\n"},{"id":"518797","messageId":"73bdcaecae585796ec212675f3a2ff92d1ec306c.1748028010.git.code@khaugsbakk.name","threadId":"63486","inReplyTo":"cover.1748028010.git.code@khaugsbakk.name","subject":"[PATCH v2 9/9] doc: notes: use stuck form throughout","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2025-05-23T19:29:55Z","receivedAt":"2025-05-23T19:32:20Z","isPatch":true,"sender":{"key":"kristofferhaugsbakk@fastmail.com","avatar":null},"body":"From: Kristoffer Haugsbakk \n\ngitcli(7) recommends the *stuck form*. `--ref` is the only one which\ndoes not use it.\n\nSigned-off-by: Kristoffer Haugsbakk \n---\n\nNotes (series):\n v2:\n • New\n • I didn’t spot this in the first round. Hopefully it’s fine to include\n it as well while we are editing this file. I would consider making a\n separate thread if I wasn’t editing nearby hunks.\n\n Documentation/git-notes.adoc | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/Documentation/git-notes.adoc b/Documentation/git-notes.adoc\nindex a0167af5aba..43436daeccc 100644\n--- a/Documentation/git-notes.adoc\n+++ b/Documentation/git-notes.adoc\n@@ -199,7 +199,7 @@ order of similar options. For example, for `-C -m`,\n `--stripspace` will be used because the default for `-m` overrides the\n previous `-C`.\n \n-`--ref `::\n+`--ref=`::\n \tManipulate the notes tree in __. This overrides\n \t`GIT_NOTES_REF` and the `core.notesRef` configuration. The ref\n \tspecifies the full refname when it begins with `refs/notes/`; when it\n-- \n2.49.0.780.g892193c3f50\n\n"},{"id":"518806","messageId":"xmqqiklrvwl4.fsf@gitster.g","threadId":"63486","inReplyTo":"be89c3349d24e47a38f04538d3d1e3730dfc37a9.1748028010.git.code@khaugsbakk.name","subject":"Re: [PATCH v2 6/9] doc: notes: clearly state that --stripspace is the default","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-05-23T21:36:07Z","receivedAt":"2025-05-23T21:36:09Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"kristofferhaugsbakk@fastmail.com writes:\n\n> See the review on the patch:\n> \n> https://lore.kernel.org/git/xmqq4jp326oj.fsf@gitster.g/\n> \n> There was concern about the order of options:\n> \n> > ... One more thing need to note is \"the order of\n> > the options matter\", [...]\n> \n> This sounds more like a design/implementation mistake that we may\n> want to fix.\n\nThat is a comment on the 8th iteration of the series, which is\ndifferent from what you are documenting, which is 11th if I am\nreading the thread correctly.\n\nComparing [v8 6/6] with [v11 6/7],\n\nhttps://lore.kernel.org/git/f60f743203d78a489b90df81472e71391b45367d.1682429602.git.dyroneteng@gmail.com/\nhttps://lore.kernel.org/git/19865941bb29c28a690ed3e28fc4f6870e352923.1685174012.git.dyroneteng@gmail.com/\n\nI notice that the later version has .stripspace member in note_msg\nas well as note_data. note_data has a collection of multiple\nnote_msg instances. Each of note_msg comes from various sources,\nlike '-m', '-C', etc., and each of these types have hardcoded\ndefault values for note_msg.stripspace (mostly to strip but note_msg\nthat comes from an existing note blob has stripspace unset). When\nconcat_messages() takes note_msg instances in a note_data together,\nit _could_ do:\n\n - if note_data.stripspace is explicitly specified, use that,\n otherwise use note_msg.stripspace, to cleanse the message\n contained in note_msg.\n\nand concatenate the results. But even at v11 of the series, the\nimplementation of concat_messages() uses the stripspace determined\nto instead cleanse the concatenated result.\n\nWhich I think is simply buggy.\n\nWhat it should do probably is\n\n - Loop over d->messages[] and:\n - if d->stripspace is set or d->messages[]->stripspace is set,\n cleanse the message (i.e. d->messages[]->buf) and append to d->buf\n - otherwise append d->messages[]->buf as-is to d->buf\n\n - If d->stripspace is set, cleanse d->buf (may not be necessary, as\n the messages that are concatenated have _all_ lost leading and\n trailing blank lines before concatenation).\n\nand that would truly fix the problem pointed out during the review\nof v8.\n\n> +--\n> ++\n> +`--stripspace` is the default except for\n> +`-C`/`--reuse-message`. However, keep in mind that this depends on the\n> +order of similar options. For example, for `-C -m`,\n> +`--stripspace` will be used because the default for `-m` overrides the\n> +previous `-C`.\n\nSo, I think this is an accurate description of the current\nbehaviour, but we might want to phrase the part that comes after\n\"however\" as documenting a known bug, which we would want to fix\nlater.\n\nThanks.\n\n"},{"id":"518808","messageId":"xmqqecwfvwdu.fsf@gitster.g","threadId":"63486","inReplyTo":"3e8ecf1b668277988cc5d166586105d1d5018366.1748028010.git.code@khaugsbakk.name","subject":"Re: [PATCH v2 8/9] doc: notes: treat --stdin equally between copy/remove","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-05-23T21:40:29Z","receivedAt":"2025-05-23T21:40:32Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"kristofferhaugsbakk@fastmail.com writes:\n\n> `--stdin`::\n> -\tAlso read the object names to remove notes from the standard\n> -\tinput (there is no reason you cannot combine this with object\n> -\tnames from the command line).\n> +\tFor `remove` and `copy`. See the respective subcommands.\n\nLet's phrase \"Only valid for A and B\".\n\nOtherwise, looks good. Thanks.\n"},{"id":"519018","messageId":"cover.1748380390.git.code@khaugsbakk.name","threadId":"63486","inReplyTo":"cover.1748028010.git.code@khaugsbakk.name","subject":"[PATCH v3 0/9] doc: --stdin on notes and core.commentChar mentions","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2025-05-27T21:19:29Z","receivedAt":"2025-05-27T21:19:55Z","isPatch":true,"sender":{"key":"kristofferhaugsbakk@fastmail.com","avatar":null},"body":"From: Kristoffer Haugsbakk \n\nI wanted to fix `--stdin` in the git-notes(1) documentation. Then I\nfound some other things on that doc as well as things to do with\n`core.commentChar`.\n\n§ Changes in v3\n\nSuggestions on patches 6 and 8 were implemented. See the patch notes\nand the interdiff.\n\nKristoffer Haugsbakk (9):\n doc: stripspace: mention where the default comes from\n doc: config: mention core.commentChar on commit.cleanup\n doc: notes: split out options with negated forms\n doc: notes: rework --[no-]stripspace\n doc: notes: remove stripspace discussion from other options\n doc: notes: clearly state that --stripspace is the default\n doc: notes: point out copy --stdin use with argv\n doc: notes: treat --stdin equally between copy/remove\n doc: notes: use stuck form throughout\n\n Documentation/config/commit.adoc | 7 ++--\n Documentation/git-notes.adoc | 54 ++++++++++++++++++-------------\n Documentation/git-stripspace.adoc | 3 +-\n 3 files changed, 38 insertions(+), 26 deletions(-)\n\nInterdiff against v2:\ndiff --git a/Documentation/git-notes.adoc b/Documentation/git-notes.adoc\nindex 43436daeccc..46a232ca718 100644\n--- a/Documentation/git-notes.adoc\n+++ b/Documentation/git-notes.adoc\n@@ -197,7 +197,8 @@ OPTIONS\n `-C`/`--reuse-message`. However, keep in mind that this depends on the\n order of similar options. For example, for `-C -m`,\n `--stripspace` will be used because the default for `-m` overrides the\n-previous `-C`.\n+previous `-C`. This is a known limitation that may be fixed in the\n+future.\n \n `--ref=`::\n \tManipulate the notes tree in __. This overrides\n@@ -211,7 +212,7 @@ previous `-C`.\n \tobject that does not have notes attached to it.\n \n `--stdin`::\n-\tFor `remove` and `copy`. See the respective subcommands.\n+\tOnly valid for `remove` and `copy`. See the respective subcommands.\n \n `-n`::\n `--dry-run`::\nRange-diff against v2:\n 1: bf3ea7f23c0 = 1: bf3ea7f23c0 doc: stripspace: mention where the default comes from\n 2: e9cf956a824 = 2: e9cf956a824 doc: config: mention core.commentChar on commit.cleanup\n 3: 14dc58120e3 = 3: 14dc58120e3 doc: notes: split out options with negated forms\n 4: c68a91f81ba = 4: c68a91f81ba doc: notes: rework --[no-]stripspace\n 5: f4755040f38 = 5: f4755040f38 doc: notes: remove stripspace discussion from other options\n 6: be89c3349d2 ! 6: 184cf032abf doc: notes: clearly state that --stripspace is the default\n @@ Commit message\n Clearly state when which of the regular and negated form of the\n option take effect.[1]\n \n + Also mention the subtle behavior that occurs when you mix options like\n + `-m` and `-C`, including a note that it might be fixed in the future.\n + The topic was brought up on v8 of the `--separator` series.[2][3]\n +\n [1]: https://lore.kernel.org/git/xmqqcyct1mtq.fsf@gitster.g/\n + [2]: https://lore.kernel.org/git/xmqq4jp326oj.fsf@gitster.g/\n + † 3: v11 was the version that landed\n \n + Helped-by: Junio C Hamano \n Signed-off-by: Kristoffer Haugsbakk \n \n \n ## Notes (series) ##\n + v3:\n + • Mention that it is a bug (“known limitation”) which might be fixed.\n +\n + Link: https://lore.kernel.org/git/xmqqiklrvwl4.fsf@gitster.g/\n + • Message: discuss this new “subtle behavior” part\n v2:\n • New\n • The `--` are to prevent the new paragraph from becoming a continuation\n @@ Documentation/git-notes.adoc: OPTIONS\n +`-C`/`--reuse-message`. However, keep in mind that this depends on the\n +order of similar options. For example, for `-C -m`,\n +`--stripspace` will be used because the default for `-m` overrides the\n -+previous `-C`.\n ++previous `-C`. This is a known limitation that may be fixed in the\n ++future.\n \n `--ref `::\n \tManipulate the notes tree in __. This overrides\n 7: d8a22847a7d = 7: e18472f735d doc: notes: point out copy --stdin use with argv\n 8: 3e8ecf1b668 ! 8: 530dd953170 doc: notes: treat --stdin equally between copy/remove\n @@ Commit message\n \n \n ## Notes (series) ##\n + v3:\n + • Rephrase to “Only valid for”\n +\n + Link: https://lore.kernel.org/git/xmqqecwfvwdu.fsf@gitster.g/\n v2:\n • On --stdin: just refer to the respective subcommands and stop there.\n As suggested.\n @@ Documentation/git-notes.adoc: When done, the user can either finalize the merge\n \n `prune`::\n \tRemove all notes for non-existing/unreachable objects.\n -@@ Documentation/git-notes.adoc: previous `-C`.\n +@@ Documentation/git-notes.adoc: future.\n \tobject that does not have notes attached to it.\n \n `--stdin`::\n -\tAlso read the object names to remove notes from the standard\n -\tinput (there is no reason you cannot combine this with object\n -\tnames from the command line).\n -+\tFor `remove` and `copy`. See the respective subcommands.\n ++\tOnly valid for `remove` and `copy`. See the respective subcommands.\n \n `-n`::\n `--dry-run`::\n 9: 73bdcaecae5 ! 9: 7751330daa4 doc: notes: use stuck form throughout\n @@ Notes (series)\n \n ## Documentation/git-notes.adoc ##\n @@ Documentation/git-notes.adoc: order of similar options. For example, for `-C -m`,\n - `--stripspace` will be used because the default for `-m` overrides the\n - previous `-C`.\n + previous `-C`. This is a known limitation that may be fixed in the\n + future.\n \n -`--ref `::\n +`--ref=`::\n\nbase-commit: cb96e1697ad6e54d11fc920c95f82977f8e438f8\n-- \n2.49.0.780.g892193c3f50\n\n"},{"id":"519019","messageId":"bf3ea7f23c08b5c477fedd42e2a0e518607c8ec6.1748380390.git.code@khaugsbakk.name","threadId":"63486","inReplyTo":"cover.1748380390.git.code@khaugsbakk.name","subject":"[PATCH v3 1/9] doc: stripspace: mention where the default comes from","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2025-05-27T21:19:30Z","receivedAt":"2025-05-27T21:19:59Z","isPatch":true,"sender":{"key":"kristofferhaugsbakk@fastmail.com","avatar":null},"body":"From: Kristoffer Haugsbakk \n\nAlso quote `#` in line with the modern formatting convention.\n\nSigned-off-by: Kristoffer Haugsbakk \n---\n\nNotes (series):\n v2:\n • More terse mention of the default as well as the configuration\n variable. Don’t link to git-config(1), there’s no real need.\n \n Link: https://lore.kernel.org/git/xmqqjz6bhzkm.fsf@gitster.g/\n v1:\n • “modern formatting convention”\n \n It looks like characters are quoted with backticks in the commits I’ve\n seen by Jean-Noël Avila lately.\n\n Documentation/git-stripspace.adoc | 3 ++-\n 1 file changed, 2 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/git-stripspace.adoc b/Documentation/git-stripspace.adoc\nindex a293327581a..37287f211f0 100644\n--- a/Documentation/git-stripspace.adoc\n+++ b/Documentation/git-stripspace.adoc\n@@ -37,7 +37,8 @@ OPTIONS\n -------\n -s::\n --strip-comments::\n-\tSkip and remove all lines starting with a comment character (default '#').\n+\tSkip and remove all lines starting with a comment character\n+\t(`core.commentChar`, default `#`).\n \n -c::\n --comment-lines::\n-- \n2.49.0.780.g892193c3f50\n\n"},{"id":"519020","messageId":"e9cf956a824c888b7313d6a2ff5c513374b3e40e.1748380390.git.code@khaugsbakk.name","threadId":"63486","inReplyTo":"cover.1748380390.git.code@khaugsbakk.name","subject":"[PATCH v3 2/9] doc: config: mention core.commentChar on commit.cleanup","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2025-05-27T21:19:31Z","receivedAt":"2025-05-27T21:20:03Z","isPatch":true,"sender":{"key":"kristofferhaugsbakk@fastmail.com","avatar":null},"body":"From: Kristoffer Haugsbakk \n\nMention it in parentheses since we are in a configuration context.\nRefer to the default as such, not as “the” character.\n\nAlso don’t mention `#` again; just say “comment character”.\n\nSigned-off-by: Kristoffer Haugsbakk \n---\n Documentation/config/commit.adoc | 7 ++++---\n 1 file changed, 4 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/config/commit.adoc b/Documentation/config/commit.adoc\nindex d3f4624fd27..208ae76c816 100644\n--- a/Documentation/config/commit.adoc\n+++ b/Documentation/config/commit.adoc\n@@ -8,10 +8,11 @@ endif::git-commit[]\n \tThis setting overrides the default of the `--cleanup` option in\n \t`git commit`. {see-git-commit} Changing the default can be useful\n \twhen you always want to keep lines that begin\n-\twith the comment character `#` in your log message, in which case you\n+\twith the comment character (`core.commentChar`, default `#`)\n+\tin your log message, in which case you\n \twould do `git config commit.cleanup whitespace` (note that you will\n-\thave to remove the help lines that begin with `#` in the commit log\n-\ttemplate yourself, if you do this).\n+\thave to remove the help lines that begin with the comment character\n+\tin the commit log template yourself, if you do this).\n \n `commit.gpgSign`::\n \tA boolean to specify whether all commits should be GPG signed.\n-- \n2.49.0.780.g892193c3f50\n\n"},{"id":"519021","messageId":"14dc58120e3da564e28e1b442d481d632c28aeab.1748380390.git.code@khaugsbakk.name","threadId":"63486","inReplyTo":"cover.1748380390.git.code@khaugsbakk.name","subject":"[PATCH v3 3/9] doc: notes: split out options with negated forms","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2025-05-27T21:19:32Z","receivedAt":"2025-05-27T21:20:07Z","isPatch":true,"sender":{"key":"kristofferhaugsbakk@fastmail.com","avatar":null},"body":"From: Kristoffer Haugsbakk \n\nSplit these out so that they are easier to search for.[1]\n\n[1]: https://lore.kernel.org/git/xmqqcyct1mtq.fsf@gitster.g/\n\nSigned-off-by: Kristoffer Haugsbakk \n---\n\nNotes (series):\n v2:\n • Message: Use “negated form” since that seems more typical\n\n Documentation/git-notes.adoc | 6 ++++--\n 1 file changed, 4 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/git-notes.adoc b/Documentation/git-notes.adoc\nindex bcfe3dacd3f..8706b33f2ee 100644\n--- a/Documentation/git-notes.adoc\n+++ b/Documentation/git-notes.adoc\n@@ -174,14 +174,16 @@ OPTIONS\n \tAllow an empty note object to be stored. The default behavior is\n \tto automatically remove empty notes.\n \n-`--[no-]separator`::\n `--separator=`::\n+`--separator`::\n+`--no-separator`::\n \tSpecify a string used as a custom inter-paragraph separator\n \t(a newline is added at the end as needed). If `--no-separator`, no\n \tseparators will be added between paragraphs. Defaults to a blank\n \tline.\n \n-`--[no-]stripspace`::\n+`--stripspace`::\n+`--no-stripspace`::\n \tStrip leading and trailing whitespace from the note message.\n \tAlso strip out empty lines other than a single line between\n \tparagraphs. Lines starting with `#` will be stripped out\n-- \n2.49.0.780.g892193c3f50\n\n"},{"id":"519022","messageId":"c68a91f81ba180acb1025b229dee3d1e61691e75.1748380390.git.code@khaugsbakk.name","threadId":"63486","inReplyTo":"cover.1748380390.git.code@khaugsbakk.name","subject":"[PATCH v3 4/9] doc: notes: rework --[no-]stripspace","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2025-05-27T21:19:33Z","receivedAt":"2025-05-27T21:20:12Z","isPatch":true,"sender":{"key":"kristofferhaugsbakk@fastmail.com","avatar":null},"body":"From: Kristoffer Haugsbakk \n\nDocument this option by copying the bullet list from git-stripspace(1).\nA bullet list is cleaner when there are this many points to consider.\nWe also get a more standardized description of the multiple-blank-lines\nbehavior. Compare the repeating (git-notes(1)):\n\n empty lines other than a single line between paragraphs\n\nWith (git-stripspace(1)):\n\n multiple consecutive empty lines\n\nAnd:\n\n leading [...] whitespace\n\nWith:\n\n empty lines from the beginning\n\nLeading whitespace in the form of spaces (indentation) are not removed.\nHowever, empty lines at the start of the message are removed.\n\nNote that we drop the mentions of comment line handling because they are\nwrong; this option does not control how lines which can be recognized as\ncomment lines are handled. Only interactivity controls that:\n\n• Comment lines are stripped after editing interactively\n• Lines which could be recognized as comment lines are left alone when\n the message is given non-interactively\n\nSo it is misleading to document the comment line behavior on\nthis option.\n\nFurther, the text is wrong:\n\n Lines starting with `#` will be stripped out in non-editor cases\n like `-m`, [...]\n\nComment lines are still indirectly discussed on other options. We will\ndeal with them in the next commit.\n\nSigned-off-by: Kristoffer Haugsbakk \n---\n\nNotes (series):\n v2:\n • New\n • Together with one other other patch replaces v1 patch “doc: notes:\n mention comment character configuration”\n • I figured out that mentioning the comment character/comment lines\n doesn’t make sense here. So all attempts to rephrase “comment\n character” or “lines that start with `#`” are gone\n\n Documentation/git-notes.adoc | 12 +++++++-----\n 1 file changed, 7 insertions(+), 5 deletions(-)\n\ndiff --git a/Documentation/git-notes.adoc b/Documentation/git-notes.adoc\nindex 8706b33f2ee..d672794a942 100644\n--- a/Documentation/git-notes.adoc\n+++ b/Documentation/git-notes.adoc\n@@ -184,11 +184,13 @@ OPTIONS\n \n `--stripspace`::\n `--no-stripspace`::\n-\tStrip leading and trailing whitespace from the note message.\n-\tAlso strip out empty lines other than a single line between\n-\tparagraphs. Lines starting with `#` will be stripped out\n-\tin non-editor cases like `-m`, `-F` and `-C`, but not in\n-\teditor case like `git notes edit`, `-c`, etc.\n+\tClean up whitespace. Specifically (see\n+\tlinkgit:git-stripspace[1]):\n++\n+- remove trailing whitespace from all lines\n+- collapse multiple consecutive empty lines into one empty line\n+- remove empty lines from the beginning and end of the input\n+- add a missing `\\n` to the last line if necessary.\n \n `--ref `::\n \tManipulate the notes tree in __. This overrides\n-- \n2.49.0.780.g892193c3f50\n\n"},{"id":"519023","messageId":"f4755040f38170b508e9cba03a7226b5b4d5cd9c.1748380390.git.code@khaugsbakk.name","threadId":"63486","inReplyTo":"cover.1748380390.git.code@khaugsbakk.name","subject":"[PATCH v3 5/9] doc: notes: remove stripspace discussion from other options","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2025-05-27T21:19:34Z","receivedAt":"2025-05-27T21:20:15Z","isPatch":true,"sender":{"key":"kristofferhaugsbakk@fastmail.com","avatar":null},"body":"From: Kristoffer Haugsbakk \n\nCleaning up whitespace in metadata is typical porcelain behavior and\nthis default does not need to be pointed out.[1] Only speak up when\nthe default `--stripspace` is not used.\n\nAlso remove all misleading mentions of comment lines in the process;\nsee the previous commit.\n\nAlso remove the period that trails the parenthetical here.\n\n† 1: See `-F` in git-commit(1) which has nothing to say about whitespace\n cleanup. The cleanup discussion is on `--cleanup`.\n\nSigned-off-by: Kristoffer Haugsbakk \n---\n\nNotes (series):\n v2:\n • New\n • Together with one other patch replaces v1 patch “doc: notes:\n mention comment character configuration”\n • I figured out that mentioning the comment character/comment lines\n doesn’t make sense here. So all attempts to rephrase “comment\n character” or “lines that start with `#`” are gone\n\n Documentation/git-notes.adoc | 12 ++----------\n 1 file changed, 2 insertions(+), 10 deletions(-)\n\ndiff --git a/Documentation/git-notes.adoc b/Documentation/git-notes.adoc\nindex d672794a942..383e8bca685 100644\n--- a/Documentation/git-notes.adoc\n+++ b/Documentation/git-notes.adoc\n@@ -144,26 +144,18 @@ OPTIONS\n \tUse the given note message (instead of prompting).\n \tIf multiple `-m` options are given, their values\n \tare concatenated as separate paragraphs.\n-\tLines starting with `#` and empty lines other than a\n-\tsingle line between paragraphs will be stripped out.\n-\tIf you wish to keep them verbatim, use `--no-stripspace`.\n \n `-F `::\n `--file=`::\n \tTake the note message from the given file. Use `-` to\n \tread the note message from the standard input.\n-\tLines starting with `#` and empty lines other than a\n-\tsingle line between paragraphs will be stripped out.\n-\tIf you wish to keep them verbatim, use `--no-stripspace`.\n \n `-C `::\n `--reuse-message=`::\n \tTake the given blob object (for example, another note) as the\n \tnote message. (Use `git notes copy ` instead to\n-\tcopy notes between objects.). By default, message will be\n-\tcopied verbatim, but if you wish to strip out the lines\n-\tstarting with `#` and empty lines other than a single line\n-\tbetween paragraphs, use with `--stripspace` option.\n+\tcopy notes between objects.) Implies `--no-stripspace` since\n+\tthe default behavior is to copy the message verbatim.\n \n `-c `::\n `--reedit-message=`::\n-- \n2.49.0.780.g892193c3f50\n\n"},{"id":"519024","messageId":"184cf032abf477eae06cd1b9f44da0ddab27b44e.1748380390.git.code@khaugsbakk.name","threadId":"63486","inReplyTo":"cover.1748380390.git.code@khaugsbakk.name","subject":"[PATCH v3 6/9] doc: notes: clearly state that --stripspace is the default","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2025-05-27T21:19:35Z","receivedAt":"2025-05-27T21:20:19Z","isPatch":true,"sender":{"key":"kristofferhaugsbakk@fastmail.com","avatar":null},"body":"From: Kristoffer Haugsbakk \n\nClearly state when which of the regular and negated form of the\noption take effect.[1]\n\nAlso mention the subtle behavior that occurs when you mix options like\n`-m` and `-C`, including a note that it might be fixed in the future.\nThe topic was brought up on v8 of the `--separator` series.[2][3]\n\n[1]: https://lore.kernel.org/git/xmqqcyct1mtq.fsf@gitster.g/\n[2]: https://lore.kernel.org/git/xmqq4jp326oj.fsf@gitster.g/\n† 3: v11 was the version that landed\n\nHelped-by: Junio C Hamano \nSigned-off-by: Kristoffer Haugsbakk \n---\n\nNotes (series):\n v3:\n • Mention that it is a bug (“known limitation”) which might be fixed.\n \n Link: https://lore.kernel.org/git/xmqqiklrvwl4.fsf@gitster.g/\n • Message: discuss this new “subtle behavior” part\n v2:\n • New\n • The `--` are to prevent the new paragraph from becoming a continuation\n of the last bullet point\n • Junio pointed out that I didn’t go over the part about checking\n which variant (regular or negation) are the default. See the link:\n \n https://lore.kernel.org/git/xmqqcyct1mtq.fsf@gitster.g/\n \n I decided to do this on this series.\n \n Link: https://lore.kernel.org/git/xmqqfrgzhzbp.fsf@gitster.g/\n • The last part of the paragraph is based on the commit message of\n c4e2aa7d45f (notes.c: introduce \"--[no-]stripspace\" option,\n 2023-05-27).\n \n See the review on the patch:\n \n https://lore.kernel.org/git/xmqq4jp326oj.fsf@gitster.g/\n \n There was concern about the order of options:\n \n > ... One more thing need to note is \"the order of\n > the options matter\", [...]\n \n This sounds more like a design/implementation mistake that we may\n want to fix.\n \n This new part is supposed to address that.\n\n Documentation/git-notes.adoc | 9 +++++++++\n 1 file changed, 9 insertions(+)\n\ndiff --git a/Documentation/git-notes.adoc b/Documentation/git-notes.adoc\nindex 383e8bca685..ef5a939516e 100644\n--- a/Documentation/git-notes.adoc\n+++ b/Documentation/git-notes.adoc\n@@ -179,10 +179,19 @@ OPTIONS\n \tClean up whitespace. Specifically (see\n \tlinkgit:git-stripspace[1]):\n +\n+--\n - remove trailing whitespace from all lines\n - collapse multiple consecutive empty lines into one empty line\n - remove empty lines from the beginning and end of the input\n - add a missing `\\n` to the last line if necessary.\n+--\n++\n+`--stripspace` is the default except for\n+`-C`/`--reuse-message`. However, keep in mind that this depends on the\n+order of similar options. For example, for `-C -m`,\n+`--stripspace` will be used because the default for `-m` overrides the\n+previous `-C`. This is a known limitation that may be fixed in the\n+future.\n \n `--ref `::\n \tManipulate the notes tree in __. This overrides\n-- \n2.49.0.780.g892193c3f50\n\n"},{"id":"519025","messageId":"e18472f735d658656f7fdbc21ccc5befa63feb85.1748380390.git.code@khaugsbakk.name","threadId":"63486","inReplyTo":"cover.1748380390.git.code@khaugsbakk.name","subject":"[PATCH v3 7/9] doc: notes: point out copy --stdin use with argv","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2025-05-27T21:19:36Z","receivedAt":"2025-05-27T21:20:22Z","isPatch":true,"sender":{"key":"kristofferhaugsbakk@fastmail.com","avatar":null},"body":"From: Kristoffer Haugsbakk \n\nUnlike `remove --stdin`, this option cannot be combined with object\nnames given via the command line.\n\nSigned-off-by: Kristoffer Haugsbakk \n---\n Documentation/git-notes.adoc | 3 +++\n 1 file changed, 3 insertions(+)\n\ndiff --git a/Documentation/git-notes.adoc b/Documentation/git-notes.adoc\nindex ef5a939516e..9ce71ec3455 100644\n--- a/Documentation/git-notes.adoc\n+++ b/Documentation/git-notes.adoc\n@@ -87,6 +87,9 @@ In `--stdin` mode, take lines in the format\n on standard input, and copy the notes from each __ to its\n corresponding __. (The optional __ is ignored so that\n the command can read the input given to the `post-rewrite` hook.)\n++\n+`--stdin` cannot be combined with object names given on the command\n+line.\n \n `append`::\n \tAppend new message(s) given by `-m` or `-F` options to an\n-- \n2.49.0.780.g892193c3f50\n\n"},{"id":"519026","messageId":"530dd953170e14ff02dfb6c84b1188745a8b1501.1748380390.git.code@khaugsbakk.name","threadId":"63486","inReplyTo":"cover.1748380390.git.code@khaugsbakk.name","subject":"[PATCH v3 8/9] doc: notes: treat --stdin equally between copy/remove","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2025-05-27T21:19:37Z","receivedAt":"2025-05-27T21:20:26Z","isPatch":true,"sender":{"key":"kristofferhaugsbakk@fastmail.com","avatar":null},"body":"From: Kristoffer Haugsbakk \n\n46538012d94 (notes remove: --stdin reads from the standard input,\n2011-05-18) added `--stdin` for the `remove` subcommand, documenting it\nin the “Options” section. But `copy --stdin` was added before that, in\n160baa0d9cb (notes: implement 'git notes copy --stdin', 2010-03-12).\n\nTreat this option equally between the two subcommands:\n\n• remove: mention `--stdin` on the subcommand as well, like for `copy`\n• copy: mention it as well under the option documentation\n\nSigned-off-by: Kristoffer Haugsbakk \n---\n\nNotes (series):\n v3:\n • Rephrase to “Only valid for”\n \n Link: https://lore.kernel.org/git/xmqqecwfvwdu.fsf@gitster.g/\n v2:\n • On --stdin: just refer to the respective subcommands and stop there.\n As suggested.\n \n Link: https://lore.kernel.org/git/xmqq34czhyz8.fsf@gitster.g/\n\n Documentation/git-notes.adoc | 8 +++++---\n 1 file changed, 5 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/git-notes.adoc b/Documentation/git-notes.adoc\nindex 9ce71ec3455..397f6caa92a 100644\n--- a/Documentation/git-notes.adoc\n+++ b/Documentation/git-notes.adoc\n@@ -127,6 +127,10 @@ When done, the user can either finalize the merge with\n \tgiving zero or one object from the command line, this is\n \tequivalent to specifying an empty note message to\n \tthe `edit` subcommand.\n++\n+In `--stdin` mode, also remove the object names given on standard\n+input. In other words, `--stdin` can be combined with object names from\n+the command line.\n \n `prune`::\n \tRemove all notes for non-existing/unreachable objects.\n@@ -208,9 +212,7 @@ future.\n \tobject that does not have notes attached to it.\n \n `--stdin`::\n-\tAlso read the object names to remove notes from the standard\n-\tinput (there is no reason you cannot combine this with object\n-\tnames from the command line).\n+\tOnly valid for `remove` and `copy`. See the respective subcommands.\n \n `-n`::\n `--dry-run`::\n-- \n2.49.0.780.g892193c3f50\n\n"},{"id":"519027","messageId":"7751330daa4fe28f4c989e9d27e9701bb21bc0f2.1748380390.git.code@khaugsbakk.name","threadId":"63486","inReplyTo":"cover.1748380390.git.code@khaugsbakk.name","subject":"[PATCH v3 9/9] doc: notes: use stuck form throughout","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2025-05-27T21:19:38Z","receivedAt":"2025-05-27T21:20:31Z","isPatch":true,"sender":{"key":"kristofferhaugsbakk@fastmail.com","avatar":null},"body":"From: Kristoffer Haugsbakk \n\ngitcli(7) recommends the *stuck form*. `--ref` is the only one which\ndoes not use it.\n\nSigned-off-by: Kristoffer Haugsbakk \n---\n\nNotes (series):\n v2:\n • New\n • I didn’t spot this in the first round. Hopefully it’s fine to include\n it as well while we are editing this file. I would consider making a\n separate thread if I wasn’t editing nearby hunks.\n\n Documentation/git-notes.adoc | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/Documentation/git-notes.adoc b/Documentation/git-notes.adoc\nindex 397f6caa92a..46a232ca718 100644\n--- a/Documentation/git-notes.adoc\n+++ b/Documentation/git-notes.adoc\n@@ -200,7 +200,7 @@ order of similar options. For example, for `-C -m`,\n previous `-C`. This is a known limitation that may be fixed in the\n future.\n \n-`--ref `::\n+`--ref=`::\n \tManipulate the notes tree in __. This overrides\n \t`GIT_NOTES_REF` and the `core.notesRef` configuration. The ref\n \tspecifies the full refname when it begins with `refs/notes/`; when it\n-- \n2.49.0.780.g892193c3f50\n\n"},{"id":"519031","messageId":"xmqqr009u1k2.fsf@gitster.g","threadId":"63486","inReplyTo":"cover.1748380390.git.code@khaugsbakk.name","subject":"Re: [PATCH v3 0/9] doc: --stdin on notes and core.commentChar mentions","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-05-27T22:33:01Z","receivedAt":"2025-05-27T22:33:03Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"kristofferhaugsbakk@fastmail.com writes:\n\n> From: Kristoffer Haugsbakk \n>\n> I wanted to fix `--stdin` in the git-notes(1) documentation. Then I\n> found some other things on that doc as well as things to do with\n> `core.commentChar`.\n\nLooking really good. Let me mark the topic for 'next'.\n\nThanks.\n\n"}]}