* [PATCH v2 1/9] doc: stripspace: mention where the default comes from
2025-05-23 19:29 ` [PATCH v2 0/9] doc: --stdin on notes and core.commentChar mentions kristofferhaugsbakk
@ 2025-05-23 19:29 ` kristofferhaugsbakk
2025-05-23 19:29 ` [PATCH v2 2/9] doc: config: mention core.commentChar on commit.cleanup kristofferhaugsbakk
` (8 subsequent siblings)
9 siblings, 0 replies; 44+ messages in thread
From: kristofferhaugsbakk @ 2025-05-23 19:29 UTC (permalink / raw)
To: git; +Cc: Kristoffer Haugsbakk, Jeff King, Teng Long, D . Ben Knoble
From: Kristoffer Haugsbakk <code@khaugsbakk.name>
Also quote `#` in line with the modern formatting convention.
Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---
Notes (series):
v2:
• More terse mention of the default as well as the configuration
variable. Don’t link to git-config(1), there’s no real need.
Link: https://lore.kernel.org/git/xmqqjz6bhzkm.fsf@gitster.g/
v1:
• “modern formatting convention”
It looks like characters are quoted with backticks in the commits I’ve
seen by Jean-Noël Avila lately.
Documentation/git-stripspace.adoc | 3 ++-
1 file changed, 2 insertions(+), 1 deletion(-)
diff --git a/Documentation/git-stripspace.adoc b/Documentation/git-stripspace.adoc
index a293327581a..37287f211f0 100644
--- a/Documentation/git-stripspace.adoc
+++ b/Documentation/git-stripspace.adoc
@@ -37,7 +37,8 @@ OPTIONS
-------
-s::
--strip-comments::
- Skip and remove all lines starting with a comment character (default '#').
+ Skip and remove all lines starting with a comment character
+ (`core.commentChar`, default `#`).
-c::
--comment-lines::
--
2.49.0.780.g892193c3f50
^ permalink raw reply related [flat|nested] 44+ messages in thread* [PATCH v2 2/9] doc: config: mention core.commentChar on commit.cleanup
2025-05-23 19:29 ` [PATCH v2 0/9] doc: --stdin on notes and core.commentChar mentions kristofferhaugsbakk
2025-05-23 19:29 ` [PATCH v2 1/9] doc: stripspace: mention where the default comes from kristofferhaugsbakk
@ 2025-05-23 19:29 ` kristofferhaugsbakk
2025-05-23 19:29 ` [PATCH v2 3/9] doc: notes: split out options with negated forms kristofferhaugsbakk
` (7 subsequent siblings)
9 siblings, 0 replies; 44+ messages in thread
From: kristofferhaugsbakk @ 2025-05-23 19:29 UTC (permalink / raw)
To: git; +Cc: Kristoffer Haugsbakk, Jeff King, Teng Long, D . Ben Knoble
From: Kristoffer Haugsbakk <code@khaugsbakk.name>
Mention it in parentheses since we are in a configuration context.
Refer to the default as such, not as “the” character.
Also don’t mention `#` again; just say “comment character”.
Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---
Documentation/config/commit.adoc | 7 ++++---
1 file changed, 4 insertions(+), 3 deletions(-)
diff --git a/Documentation/config/commit.adoc b/Documentation/config/commit.adoc
index d3f4624fd27..208ae76c816 100644
--- a/Documentation/config/commit.adoc
+++ b/Documentation/config/commit.adoc
@@ -8,10 +8,11 @@ endif::git-commit[]
This setting overrides the default of the `--cleanup` option in
`git commit`. {see-git-commit} Changing the default can be useful
when you always want to keep lines that begin
- with the comment character `#` in your log message, in which case you
+ with the comment character (`core.commentChar`, default `#`)
+ in your log message, in which case you
would do `git config commit.cleanup whitespace` (note that you will
- have to remove the help lines that begin with `#` in the commit log
- template yourself, if you do this).
+ have to remove the help lines that begin with the comment character
+ in the commit log template yourself, if you do this).
`commit.gpgSign`::
A boolean to specify whether all commits should be GPG signed.
--
2.49.0.780.g892193c3f50
^ permalink raw reply related [flat|nested] 44+ messages in thread* [PATCH v2 3/9] doc: notes: split out options with negated forms
2025-05-23 19:29 ` [PATCH v2 0/9] doc: --stdin on notes and core.commentChar mentions kristofferhaugsbakk
2025-05-23 19:29 ` [PATCH v2 1/9] doc: stripspace: mention where the default comes from kristofferhaugsbakk
2025-05-23 19:29 ` [PATCH v2 2/9] doc: config: mention core.commentChar on commit.cleanup kristofferhaugsbakk
@ 2025-05-23 19:29 ` kristofferhaugsbakk
2025-05-23 19:29 ` [PATCH v2 4/9] doc: notes: rework --[no-]stripspace kristofferhaugsbakk
` (6 subsequent siblings)
9 siblings, 0 replies; 44+ messages in thread
From: kristofferhaugsbakk @ 2025-05-23 19:29 UTC (permalink / raw)
To: git; +Cc: Kristoffer Haugsbakk, Jeff King, Teng Long, D . Ben Knoble
From: Kristoffer Haugsbakk <code@khaugsbakk.name>
Split these out so that they are easier to search for.[1]
[1]: https://lore.kernel.org/git/xmqqcyct1mtq.fsf@gitster.g/
Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---
Notes (series):
v2:
• Message: Use “negated form” since that seems more typical
Documentation/git-notes.adoc | 6 ++++--
1 file changed, 4 insertions(+), 2 deletions(-)
diff --git a/Documentation/git-notes.adoc b/Documentation/git-notes.adoc
index bcfe3dacd3f..8706b33f2ee 100644
--- a/Documentation/git-notes.adoc
+++ b/Documentation/git-notes.adoc
@@ -174,14 +174,16 @@ OPTIONS
Allow an empty note object to be stored. The default behavior is
to automatically remove empty notes.
-`--[no-]separator`::
`--separator=<paragraph-break>`::
+`--separator`::
+`--no-separator`::
Specify a string used as a custom inter-paragraph separator
(a newline is added at the end as needed). If `--no-separator`, no
separators will be added between paragraphs. Defaults to a blank
line.
-`--[no-]stripspace`::
+`--stripspace`::
+`--no-stripspace`::
Strip leading and trailing whitespace from the note message.
Also strip out empty lines other than a single line between
paragraphs. Lines starting with `#` will be stripped out
--
2.49.0.780.g892193c3f50
^ permalink raw reply related [flat|nested] 44+ messages in thread* [PATCH v2 4/9] doc: notes: rework --[no-]stripspace
2025-05-23 19:29 ` [PATCH v2 0/9] doc: --stdin on notes and core.commentChar mentions kristofferhaugsbakk
` (2 preceding siblings ...)
2025-05-23 19:29 ` [PATCH v2 3/9] doc: notes: split out options with negated forms kristofferhaugsbakk
@ 2025-05-23 19:29 ` kristofferhaugsbakk
2025-05-23 19:29 ` [PATCH v2 5/9] doc: notes: remove stripspace discussion from other options kristofferhaugsbakk
` (5 subsequent siblings)
9 siblings, 0 replies; 44+ messages in thread
From: kristofferhaugsbakk @ 2025-05-23 19:29 UTC (permalink / raw)
To: git; +Cc: Kristoffer Haugsbakk, Jeff King, Teng Long, D . Ben Knoble
From: Kristoffer Haugsbakk <code@khaugsbakk.name>
Document this option by copying the bullet list from git-stripspace(1).
A bullet list is cleaner when there are this many points to consider.
We also get a more standardized description of the multiple-blank-lines
behavior. Compare the repeating (git-notes(1)):
empty lines other than a single line between paragraphs
With (git-stripspace(1)):
multiple consecutive empty lines
And:
leading [...] whitespace
With:
empty lines from the beginning
Leading whitespace in the form of spaces (indentation) are not removed.
However, empty lines at the start of the message are removed.
Note that we drop the mentions of comment line handling because they are
wrong; this option does not control how lines which can be recognized as
comment lines are handled. Only interactivity controls that:
• Comment lines are stripped after editing interactively
• Lines which could be recognized as comment lines are left alone when
the message is given non-interactively
So it is misleading to document the comment line behavior on
this option.
Further, the text is wrong:
Lines starting with `#` will be stripped out in non-editor cases
like `-m`, [...]
Comment lines are still indirectly discussed on other options. We will
deal with them in the next commit.
Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---
Notes (series):
v2:
• New
• Together with one other other patch replaces v1 patch “doc: notes:
mention comment character configuration”
• I figured out that mentioning the comment character/comment lines
doesn’t make sense here. So all attempts to rephrase “comment
character” or “lines that start with `#`” are gone
Documentation/git-notes.adoc | 12 +++++++-----
1 file changed, 7 insertions(+), 5 deletions(-)
diff --git a/Documentation/git-notes.adoc b/Documentation/git-notes.adoc
index 8706b33f2ee..d672794a942 100644
--- a/Documentation/git-notes.adoc
+++ b/Documentation/git-notes.adoc
@@ -184,11 +184,13 @@ OPTIONS
`--stripspace`::
`--no-stripspace`::
- Strip leading and trailing whitespace from the note message.
- Also strip out empty lines other than a single line between
- paragraphs. Lines starting with `#` will be stripped out
- in non-editor cases like `-m`, `-F` and `-C`, but not in
- editor case like `git notes edit`, `-c`, etc.
+ Clean up whitespace. Specifically (see
+ linkgit:git-stripspace[1]):
++
+- remove trailing whitespace from all lines
+- collapse multiple consecutive empty lines into one empty line
+- remove empty lines from the beginning and end of the input
+- add a missing `\n` to the last line if necessary.
`--ref <ref>`::
Manipulate the notes tree in _<ref>_. This overrides
--
2.49.0.780.g892193c3f50
^ permalink raw reply related [flat|nested] 44+ messages in thread* [PATCH v2 5/9] doc: notes: remove stripspace discussion from other options
2025-05-23 19:29 ` [PATCH v2 0/9] doc: --stdin on notes and core.commentChar mentions kristofferhaugsbakk
` (3 preceding siblings ...)
2025-05-23 19:29 ` [PATCH v2 4/9] doc: notes: rework --[no-]stripspace kristofferhaugsbakk
@ 2025-05-23 19:29 ` kristofferhaugsbakk
2025-05-23 19:29 ` [PATCH v2 6/9] doc: notes: clearly state that --stripspace is the default kristofferhaugsbakk
` (4 subsequent siblings)
9 siblings, 0 replies; 44+ messages in thread
From: kristofferhaugsbakk @ 2025-05-23 19:29 UTC (permalink / raw)
To: git; +Cc: Kristoffer Haugsbakk, Jeff King, Teng Long, D . Ben Knoble
From: Kristoffer Haugsbakk <code@khaugsbakk.name>
Cleaning up whitespace in metadata is typical porcelain behavior and
this default does not need to be pointed out.[1] Only speak up when
the default `--stripspace` is not used.
Also remove all misleading mentions of comment lines in the process;
see the previous commit.
Also remove the period that trails the parenthetical here.
† 1: See `-F` in git-commit(1) which has nothing to say about whitespace
cleanup. The cleanup discussion is on `--cleanup`.
Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---
Notes (series):
v2:
• New
• Together with one other patch replaces v1 patch “doc: notes:
mention comment character configuration”
• I figured out that mentioning the comment character/comment lines
doesn’t make sense here. So all attempts to rephrase “comment
character” or “lines that start with `#`” are gone
Documentation/git-notes.adoc | 12 ++----------
1 file changed, 2 insertions(+), 10 deletions(-)
diff --git a/Documentation/git-notes.adoc b/Documentation/git-notes.adoc
index d672794a942..383e8bca685 100644
--- a/Documentation/git-notes.adoc
+++ b/Documentation/git-notes.adoc
@@ -144,26 +144,18 @@ OPTIONS
Use the given note message (instead of prompting).
If multiple `-m` options are given, their values
are concatenated as separate paragraphs.
- Lines starting with `#` and empty lines other than a
- single line between paragraphs will be stripped out.
- If you wish to keep them verbatim, use `--no-stripspace`.
`-F <file>`::
`--file=<file>`::
Take the note message from the given file. Use `-` to
read the note message from the standard input.
- Lines starting with `#` and empty lines other than a
- single line between paragraphs will be stripped out.
- If you wish to keep them verbatim, use `--no-stripspace`.
`-C <object>`::
`--reuse-message=<object>`::
Take the given blob object (for example, another note) as the
note message. (Use `git notes copy <object>` instead to
- copy notes between objects.). By default, message will be
- copied verbatim, but if you wish to strip out the lines
- starting with `#` and empty lines other than a single line
- between paragraphs, use with `--stripspace` option.
+ copy notes between objects.) Implies `--no-stripspace` since
+ the default behavior is to copy the message verbatim.
`-c <object>`::
`--reedit-message=<object>`::
--
2.49.0.780.g892193c3f50
^ permalink raw reply related [flat|nested] 44+ messages in thread* [PATCH v2 6/9] doc: notes: clearly state that --stripspace is the default
2025-05-23 19:29 ` [PATCH v2 0/9] doc: --stdin on notes and core.commentChar mentions kristofferhaugsbakk
` (4 preceding siblings ...)
2025-05-23 19:29 ` [PATCH v2 5/9] doc: notes: remove stripspace discussion from other options kristofferhaugsbakk
@ 2025-05-23 19:29 ` kristofferhaugsbakk
2025-05-23 21:36 ` Junio C Hamano
2025-05-23 19:29 ` [PATCH v2 7/9] doc: notes: point out copy --stdin use with argv kristofferhaugsbakk
` (3 subsequent siblings)
9 siblings, 1 reply; 44+ messages in thread
From: kristofferhaugsbakk @ 2025-05-23 19:29 UTC (permalink / raw)
To: git; +Cc: Kristoffer Haugsbakk, Jeff King, Teng Long, D . Ben Knoble
From: Kristoffer Haugsbakk <code@khaugsbakk.name>
Clearly state when which of the regular and negated form of the
option take effect.[1]
[1]: https://lore.kernel.org/git/xmqqcyct1mtq.fsf@gitster.g/
Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---
Notes (series):
v2:
• New
• The `--` are to prevent the new paragraph from becoming a continuation
of the last bullet point
• Junio pointed out that I didn’t go over the part about checking
which variant (regular or negation) are the default. See the link:
https://lore.kernel.org/git/xmqqcyct1mtq.fsf@gitster.g/
I decided to do this on this series.
Link: https://lore.kernel.org/git/xmqqfrgzhzbp.fsf@gitster.g/
• The last part of the paragraph is based on the commit message of
c4e2aa7d45f (notes.c: introduce "--[no-]stripspace" option,
2023-05-27).
See the review on the patch:
https://lore.kernel.org/git/xmqq4jp326oj.fsf@gitster.g/
There was concern about the order of options:
> ... One more thing need to note is "the order of
> the options matter", [...]
This sounds more like a design/implementation mistake that we may
want to fix.
This new part is supposed to address that.
Documentation/git-notes.adoc | 8 ++++++++
1 file changed, 8 insertions(+)
diff --git a/Documentation/git-notes.adoc b/Documentation/git-notes.adoc
index 383e8bca685..bad83116329 100644
--- a/Documentation/git-notes.adoc
+++ b/Documentation/git-notes.adoc
@@ -179,10 +179,18 @@ OPTIONS
Clean up whitespace. Specifically (see
linkgit:git-stripspace[1]):
+
+--
- remove trailing whitespace from all lines
- collapse multiple consecutive empty lines into one empty line
- remove empty lines from the beginning and end of the input
- add a missing `\n` to the last line if necessary.
+--
++
+`--stripspace` is the default except for
+`-C`/`--reuse-message`. However, keep in mind that this depends on the
+order of similar options. For example, for `-C <object> -m<message>`,
+`--stripspace` will be used because the default for `-m` overrides the
+previous `-C`.
`--ref <ref>`::
Manipulate the notes tree in _<ref>_. This overrides
--
2.49.0.780.g892193c3f50
^ permalink raw reply related [flat|nested] 44+ messages in thread* Re: [PATCH v2 6/9] doc: notes: clearly state that --stripspace is the default
2025-05-23 19:29 ` [PATCH v2 6/9] doc: notes: clearly state that --stripspace is the default kristofferhaugsbakk
@ 2025-05-23 21:36 ` Junio C Hamano
0 siblings, 0 replies; 44+ messages in thread
From: Junio C Hamano @ 2025-05-23 21:36 UTC (permalink / raw)
To: kristofferhaugsbakk
Cc: git, Kristoffer Haugsbakk, Jeff King, Teng Long, D . Ben Knoble
kristofferhaugsbakk@fastmail.com writes:
> See the review on the patch:
>
> https://lore.kernel.org/git/xmqq4jp326oj.fsf@gitster.g/
>
> There was concern about the order of options:
>
> > ... One more thing need to note is "the order of
> > the options matter", [...]
>
> This sounds more like a design/implementation mistake that we may
> want to fix.
That is a comment on the 8th iteration of the series, which is
different from what you are documenting, which is 11th if I am
reading the thread correctly.
Comparing [v8 6/6] with [v11 6/7],
https://lore.kernel.org/git/f60f743203d78a489b90df81472e71391b45367d.1682429602.git.dyroneteng@gmail.com/
https://lore.kernel.org/git/19865941bb29c28a690ed3e28fc4f6870e352923.1685174012.git.dyroneteng@gmail.com/
I notice that the later version has .stripspace member in note_msg
as well as note_data. note_data has a collection of multiple
note_msg instances. Each of note_msg comes from various sources,
like '-m', '-C', etc., and each of these types have hardcoded
default values for note_msg.stripspace (mostly to strip but note_msg
that comes from an existing note blob has stripspace unset). When
concat_messages() takes note_msg instances in a note_data together,
it _could_ do:
- if note_data.stripspace is explicitly specified, use that,
otherwise use note_msg.stripspace, to cleanse the message
contained in note_msg.
and concatenate the results. But even at v11 of the series, the
implementation of concat_messages() uses the stripspace determined
to instead cleanse the concatenated result.
Which I think is simply buggy.
What it should do probably is
- Loop over d->messages[] and:
- if d->stripspace is set or d->messages[]->stripspace is set,
cleanse the message (i.e. d->messages[]->buf) and append to d->buf
- otherwise append d->messages[]->buf as-is to d->buf
- If d->stripspace is set, cleanse d->buf (may not be necessary, as
the messages that are concatenated have _all_ lost leading and
trailing blank lines before concatenation).
and that would truly fix the problem pointed out during the review
of v8.
> +--
> ++
> +`--stripspace` is the default except for
> +`-C`/`--reuse-message`. However, keep in mind that this depends on the
> +order of similar options. For example, for `-C <object> -m<message>`,
> +`--stripspace` will be used because the default for `-m` overrides the
> +previous `-C`.
So, I think this is an accurate description of the current
behaviour, but we might want to phrase the part that comes after
"however" as documenting a known bug, which we would want to fix
later.
Thanks.
^ permalink raw reply [flat|nested] 44+ messages in thread
* [PATCH v2 7/9] doc: notes: point out copy --stdin use with argv
2025-05-23 19:29 ` [PATCH v2 0/9] doc: --stdin on notes and core.commentChar mentions kristofferhaugsbakk
` (5 preceding siblings ...)
2025-05-23 19:29 ` [PATCH v2 6/9] doc: notes: clearly state that --stripspace is the default kristofferhaugsbakk
@ 2025-05-23 19:29 ` kristofferhaugsbakk
2025-05-23 19:29 ` [PATCH v2 8/9] doc: notes: treat --stdin equally between copy/remove kristofferhaugsbakk
` (2 subsequent siblings)
9 siblings, 0 replies; 44+ messages in thread
From: kristofferhaugsbakk @ 2025-05-23 19:29 UTC (permalink / raw)
To: git; +Cc: Kristoffer Haugsbakk, Jeff King, Teng Long, D . Ben Knoble
From: Kristoffer Haugsbakk <code@khaugsbakk.name>
Unlike `remove --stdin`, this option cannot be combined with object
names given via the command line.
Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---
Documentation/git-notes.adoc | 3 +++
1 file changed, 3 insertions(+)
diff --git a/Documentation/git-notes.adoc b/Documentation/git-notes.adoc
index bad83116329..ad152aa94ce 100644
--- a/Documentation/git-notes.adoc
+++ b/Documentation/git-notes.adoc
@@ -87,6 +87,9 @@ In `--stdin` mode, take lines in the format
on standard input, and copy the notes from each _<from-object>_ to its
corresponding _<to-object>_. (The optional _<rest>_ is ignored so that
the command can read the input given to the `post-rewrite` hook.)
++
+`--stdin` cannot be combined with object names given on the command
+line.
`append`::
Append new message(s) given by `-m` or `-F` options to an
--
2.49.0.780.g892193c3f50
^ permalink raw reply related [flat|nested] 44+ messages in thread* [PATCH v2 8/9] doc: notes: treat --stdin equally between copy/remove
2025-05-23 19:29 ` [PATCH v2 0/9] doc: --stdin on notes and core.commentChar mentions kristofferhaugsbakk
` (6 preceding siblings ...)
2025-05-23 19:29 ` [PATCH v2 7/9] doc: notes: point out copy --stdin use with argv kristofferhaugsbakk
@ 2025-05-23 19:29 ` kristofferhaugsbakk
2025-05-23 21:40 ` Junio C Hamano
2025-05-23 19:29 ` [PATCH v2 9/9] doc: notes: use stuck form throughout kristofferhaugsbakk
2025-05-27 21:19 ` [PATCH v3 0/9] doc: --stdin on notes and core.commentChar mentions kristofferhaugsbakk
9 siblings, 1 reply; 44+ messages in thread
From: kristofferhaugsbakk @ 2025-05-23 19:29 UTC (permalink / raw)
To: git; +Cc: Kristoffer Haugsbakk, Jeff King, Teng Long, D . Ben Knoble
From: Kristoffer Haugsbakk <code@khaugsbakk.name>
46538012d94 (notes remove: --stdin reads from the standard input,
2011-05-18) added `--stdin` for the `remove` subcommand, documenting it
in the “Options” section. But `copy --stdin` was added before that, in
160baa0d9cb (notes: implement 'git notes copy --stdin', 2010-03-12).
Treat this option equally between the two subcommands:
• remove: mention `--stdin` on the subcommand as well, like for `copy`
• copy: mention it as well under the option documentation
Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---
Notes (series):
v2:
• On --stdin: just refer to the respective subcommands and stop there.
As suggested.
Link: https://lore.kernel.org/git/xmqq34czhyz8.fsf@gitster.g/
Documentation/git-notes.adoc | 8 +++++---
1 file changed, 5 insertions(+), 3 deletions(-)
diff --git a/Documentation/git-notes.adoc b/Documentation/git-notes.adoc
index ad152aa94ce..a0167af5aba 100644
--- a/Documentation/git-notes.adoc
+++ b/Documentation/git-notes.adoc
@@ -127,6 +127,10 @@ When done, the user can either finalize the merge with
giving zero or one object from the command line, this is
equivalent to specifying an empty note message to
the `edit` subcommand.
++
+In `--stdin` mode, also remove the object names given on standard
+input. In other words, `--stdin` can be combined with object names from
+the command line.
`prune`::
Remove all notes for non-existing/unreachable objects.
@@ -207,9 +211,7 @@ previous `-C`.
object that does not have notes attached to it.
`--stdin`::
- Also read the object names to remove notes from the standard
- input (there is no reason you cannot combine this with object
- names from the command line).
+ For `remove` and `copy`. See the respective subcommands.
`-n`::
`--dry-run`::
--
2.49.0.780.g892193c3f50
^ permalink raw reply related [flat|nested] 44+ messages in thread* [PATCH v2 9/9] doc: notes: use stuck form throughout
2025-05-23 19:29 ` [PATCH v2 0/9] doc: --stdin on notes and core.commentChar mentions kristofferhaugsbakk
` (7 preceding siblings ...)
2025-05-23 19:29 ` [PATCH v2 8/9] doc: notes: treat --stdin equally between copy/remove kristofferhaugsbakk
@ 2025-05-23 19:29 ` kristofferhaugsbakk
2025-05-27 21:19 ` [PATCH v3 0/9] doc: --stdin on notes and core.commentChar mentions kristofferhaugsbakk
9 siblings, 0 replies; 44+ messages in thread
From: kristofferhaugsbakk @ 2025-05-23 19:29 UTC (permalink / raw)
To: git; +Cc: Kristoffer Haugsbakk, Jeff King, Teng Long, D . Ben Knoble
From: Kristoffer Haugsbakk <code@khaugsbakk.name>
gitcli(7) recommends the *stuck form*. `--ref` is the only one which
does not use it.
Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---
Notes (series):
v2:
• New
• I didn’t spot this in the first round. Hopefully it’s fine to include
it as well while we are editing this file. I would consider making a
separate thread if I wasn’t editing nearby hunks.
Documentation/git-notes.adoc | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/Documentation/git-notes.adoc b/Documentation/git-notes.adoc
index a0167af5aba..43436daeccc 100644
--- a/Documentation/git-notes.adoc
+++ b/Documentation/git-notes.adoc
@@ -199,7 +199,7 @@ order of similar options. For example, for `-C <object> -m<message>`,
`--stripspace` will be used because the default for `-m` overrides the
previous `-C`.
-`--ref <ref>`::
+`--ref=<ref>`::
Manipulate the notes tree in _<ref>_. This overrides
`GIT_NOTES_REF` and the `core.notesRef` configuration. The ref
specifies the full refname when it begins with `refs/notes/`; when it
--
2.49.0.780.g892193c3f50
^ permalink raw reply related [flat|nested] 44+ messages in thread* [PATCH v3 0/9] doc: --stdin on notes and core.commentChar mentions
2025-05-23 19:29 ` [PATCH v2 0/9] doc: --stdin on notes and core.commentChar mentions kristofferhaugsbakk
` (8 preceding siblings ...)
2025-05-23 19:29 ` [PATCH v2 9/9] doc: notes: use stuck form throughout kristofferhaugsbakk
@ 2025-05-27 21:19 ` kristofferhaugsbakk
2025-05-27 21:19 ` [PATCH v3 1/9] doc: stripspace: mention where the default comes from kristofferhaugsbakk
` (9 more replies)
9 siblings, 10 replies; 44+ messages in thread
From: kristofferhaugsbakk @ 2025-05-27 21:19 UTC (permalink / raw)
To: git; +Cc: Kristoffer Haugsbakk, Jeff King, Teng Long, D . Ben Knoble
From: Kristoffer Haugsbakk <code@khaugsbakk.name>
I wanted to fix `--stdin` in the git-notes(1) documentation. Then I
found some other things on that doc as well as things to do with
`core.commentChar`.
§ Changes in v3
Suggestions on patches 6 and 8 were implemented. See the patch notes
and the interdiff.
Kristoffer Haugsbakk (9):
doc: stripspace: mention where the default comes from
doc: config: mention core.commentChar on commit.cleanup
doc: notes: split out options with negated forms
doc: notes: rework --[no-]stripspace
doc: notes: remove stripspace discussion from other options
doc: notes: clearly state that --stripspace is the default
doc: notes: point out copy --stdin use with argv
doc: notes: treat --stdin equally between copy/remove
doc: notes: use stuck form throughout
Documentation/config/commit.adoc | 7 ++--
Documentation/git-notes.adoc | 54 ++++++++++++++++++-------------
Documentation/git-stripspace.adoc | 3 +-
3 files changed, 38 insertions(+), 26 deletions(-)
Interdiff against v2:
diff --git a/Documentation/git-notes.adoc b/Documentation/git-notes.adoc
index 43436daeccc..46a232ca718 100644
--- a/Documentation/git-notes.adoc
+++ b/Documentation/git-notes.adoc
@@ -197,7 +197,8 @@ OPTIONS
`-C`/`--reuse-message`. However, keep in mind that this depends on the
order of similar options. For example, for `-C <object> -m<message>`,
`--stripspace` will be used because the default for `-m` overrides the
-previous `-C`.
+previous `-C`. This is a known limitation that may be fixed in the
+future.
`--ref=<ref>`::
Manipulate the notes tree in _<ref>_. This overrides
@@ -211,7 +212,7 @@ previous `-C`.
object that does not have notes attached to it.
`--stdin`::
- For `remove` and `copy`. See the respective subcommands.
+ Only valid for `remove` and `copy`. See the respective subcommands.
`-n`::
`--dry-run`::
Range-diff against v2:
1: bf3ea7f23c0 = 1: bf3ea7f23c0 doc: stripspace: mention where the default comes from
2: e9cf956a824 = 2: e9cf956a824 doc: config: mention core.commentChar on commit.cleanup
3: 14dc58120e3 = 3: 14dc58120e3 doc: notes: split out options with negated forms
4: c68a91f81ba = 4: c68a91f81ba doc: notes: rework --[no-]stripspace
5: f4755040f38 = 5: f4755040f38 doc: notes: remove stripspace discussion from other options
6: be89c3349d2 ! 6: 184cf032abf doc: notes: clearly state that --stripspace is the default
@@ Commit message
Clearly state when which of the regular and negated form of the
option take effect.[1]
+ Also mention the subtle behavior that occurs when you mix options like
+ `-m` and `-C`, including a note that it might be fixed in the future.
+ The topic was brought up on v8 of the `--separator` series.[2][3]
+
[1]: https://lore.kernel.org/git/xmqqcyct1mtq.fsf@gitster.g/
+ [2]: https://lore.kernel.org/git/xmqq4jp326oj.fsf@gitster.g/
+ † 3: v11 was the version that landed
+ Helped-by: Junio C Hamano <gitster@pobox.com>
Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
## Notes (series) ##
+ v3:
+ • Mention that it is a bug (“known limitation”) which might be fixed.
+
+ Link: https://lore.kernel.org/git/xmqqiklrvwl4.fsf@gitster.g/
+ • Message: discuss this new “subtle behavior” part
v2:
• New
• The `--` are to prevent the new paragraph from becoming a continuation
@@ Documentation/git-notes.adoc: OPTIONS
+`-C`/`--reuse-message`. However, keep in mind that this depends on the
+order of similar options. For example, for `-C <object> -m<message>`,
+`--stripspace` will be used because the default for `-m` overrides the
-+previous `-C`.
++previous `-C`. This is a known limitation that may be fixed in the
++future.
`--ref <ref>`::
Manipulate the notes tree in _<ref>_. This overrides
7: d8a22847a7d = 7: e18472f735d doc: notes: point out copy --stdin use with argv
8: 3e8ecf1b668 ! 8: 530dd953170 doc: notes: treat --stdin equally between copy/remove
@@ Commit message
## Notes (series) ##
+ v3:
+ • Rephrase to “Only valid for”
+
+ Link: https://lore.kernel.org/git/xmqqecwfvwdu.fsf@gitster.g/
v2:
• On --stdin: just refer to the respective subcommands and stop there.
As suggested.
@@ Documentation/git-notes.adoc: When done, the user can either finalize the merge
`prune`::
Remove all notes for non-existing/unreachable objects.
-@@ Documentation/git-notes.adoc: previous `-C`.
+@@ Documentation/git-notes.adoc: future.
object that does not have notes attached to it.
`--stdin`::
- Also read the object names to remove notes from the standard
- input (there is no reason you cannot combine this with object
- names from the command line).
-+ For `remove` and `copy`. See the respective subcommands.
++ Only valid for `remove` and `copy`. See the respective subcommands.
`-n`::
`--dry-run`::
9: 73bdcaecae5 ! 9: 7751330daa4 doc: notes: use stuck form throughout
@@ Notes (series)
## Documentation/git-notes.adoc ##
@@ Documentation/git-notes.adoc: order of similar options. For example, for `-C <object> -m<message>`,
- `--stripspace` will be used because the default for `-m` overrides the
- previous `-C`.
+ previous `-C`. This is a known limitation that may be fixed in the
+ future.
-`--ref <ref>`::
+`--ref=<ref>`::
base-commit: cb96e1697ad6e54d11fc920c95f82977f8e438f8
--
2.49.0.780.g892193c3f50
^ permalink raw reply related [flat|nested] 44+ messages in thread* [PATCH v3 1/9] doc: stripspace: mention where the default comes from
2025-05-27 21:19 ` [PATCH v3 0/9] doc: --stdin on notes and core.commentChar mentions kristofferhaugsbakk
@ 2025-05-27 21:19 ` kristofferhaugsbakk
2025-05-27 21:19 ` [PATCH v3 2/9] doc: config: mention core.commentChar on commit.cleanup kristofferhaugsbakk
` (8 subsequent siblings)
9 siblings, 0 replies; 44+ messages in thread
From: kristofferhaugsbakk @ 2025-05-27 21:19 UTC (permalink / raw)
To: git; +Cc: Kristoffer Haugsbakk, Jeff King, Teng Long, D . Ben Knoble
From: Kristoffer Haugsbakk <code@khaugsbakk.name>
Also quote `#` in line with the modern formatting convention.
Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---
Notes (series):
v2:
• More terse mention of the default as well as the configuration
variable. Don’t link to git-config(1), there’s no real need.
Link: https://lore.kernel.org/git/xmqqjz6bhzkm.fsf@gitster.g/
v1:
• “modern formatting convention”
It looks like characters are quoted with backticks in the commits I’ve
seen by Jean-Noël Avila lately.
Documentation/git-stripspace.adoc | 3 ++-
1 file changed, 2 insertions(+), 1 deletion(-)
diff --git a/Documentation/git-stripspace.adoc b/Documentation/git-stripspace.adoc
index a293327581a..37287f211f0 100644
--- a/Documentation/git-stripspace.adoc
+++ b/Documentation/git-stripspace.adoc
@@ -37,7 +37,8 @@ OPTIONS
-------
-s::
--strip-comments::
- Skip and remove all lines starting with a comment character (default '#').
+ Skip and remove all lines starting with a comment character
+ (`core.commentChar`, default `#`).
-c::
--comment-lines::
--
2.49.0.780.g892193c3f50
^ permalink raw reply related [flat|nested] 44+ messages in thread* [PATCH v3 2/9] doc: config: mention core.commentChar on commit.cleanup
2025-05-27 21:19 ` [PATCH v3 0/9] doc: --stdin on notes and core.commentChar mentions kristofferhaugsbakk
2025-05-27 21:19 ` [PATCH v3 1/9] doc: stripspace: mention where the default comes from kristofferhaugsbakk
@ 2025-05-27 21:19 ` kristofferhaugsbakk
2025-05-27 21:19 ` [PATCH v3 3/9] doc: notes: split out options with negated forms kristofferhaugsbakk
` (7 subsequent siblings)
9 siblings, 0 replies; 44+ messages in thread
From: kristofferhaugsbakk @ 2025-05-27 21:19 UTC (permalink / raw)
To: git; +Cc: Kristoffer Haugsbakk, Jeff King, Teng Long, D . Ben Knoble
From: Kristoffer Haugsbakk <code@khaugsbakk.name>
Mention it in parentheses since we are in a configuration context.
Refer to the default as such, not as “the” character.
Also don’t mention `#` again; just say “comment character”.
Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---
Documentation/config/commit.adoc | 7 ++++---
1 file changed, 4 insertions(+), 3 deletions(-)
diff --git a/Documentation/config/commit.adoc b/Documentation/config/commit.adoc
index d3f4624fd27..208ae76c816 100644
--- a/Documentation/config/commit.adoc
+++ b/Documentation/config/commit.adoc
@@ -8,10 +8,11 @@ endif::git-commit[]
This setting overrides the default of the `--cleanup` option in
`git commit`. {see-git-commit} Changing the default can be useful
when you always want to keep lines that begin
- with the comment character `#` in your log message, in which case you
+ with the comment character (`core.commentChar`, default `#`)
+ in your log message, in which case you
would do `git config commit.cleanup whitespace` (note that you will
- have to remove the help lines that begin with `#` in the commit log
- template yourself, if you do this).
+ have to remove the help lines that begin with the comment character
+ in the commit log template yourself, if you do this).
`commit.gpgSign`::
A boolean to specify whether all commits should be GPG signed.
--
2.49.0.780.g892193c3f50
^ permalink raw reply related [flat|nested] 44+ messages in thread* [PATCH v3 3/9] doc: notes: split out options with negated forms
2025-05-27 21:19 ` [PATCH v3 0/9] doc: --stdin on notes and core.commentChar mentions kristofferhaugsbakk
2025-05-27 21:19 ` [PATCH v3 1/9] doc: stripspace: mention where the default comes from kristofferhaugsbakk
2025-05-27 21:19 ` [PATCH v3 2/9] doc: config: mention core.commentChar on commit.cleanup kristofferhaugsbakk
@ 2025-05-27 21:19 ` kristofferhaugsbakk
2025-05-27 21:19 ` [PATCH v3 4/9] doc: notes: rework --[no-]stripspace kristofferhaugsbakk
` (6 subsequent siblings)
9 siblings, 0 replies; 44+ messages in thread
From: kristofferhaugsbakk @ 2025-05-27 21:19 UTC (permalink / raw)
To: git; +Cc: Kristoffer Haugsbakk, Jeff King, Teng Long, D . Ben Knoble
From: Kristoffer Haugsbakk <code@khaugsbakk.name>
Split these out so that they are easier to search for.[1]
[1]: https://lore.kernel.org/git/xmqqcyct1mtq.fsf@gitster.g/
Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---
Notes (series):
v2:
• Message: Use “negated form” since that seems more typical
Documentation/git-notes.adoc | 6 ++++--
1 file changed, 4 insertions(+), 2 deletions(-)
diff --git a/Documentation/git-notes.adoc b/Documentation/git-notes.adoc
index bcfe3dacd3f..8706b33f2ee 100644
--- a/Documentation/git-notes.adoc
+++ b/Documentation/git-notes.adoc
@@ -174,14 +174,16 @@ OPTIONS
Allow an empty note object to be stored. The default behavior is
to automatically remove empty notes.
-`--[no-]separator`::
`--separator=<paragraph-break>`::
+`--separator`::
+`--no-separator`::
Specify a string used as a custom inter-paragraph separator
(a newline is added at the end as needed). If `--no-separator`, no
separators will be added between paragraphs. Defaults to a blank
line.
-`--[no-]stripspace`::
+`--stripspace`::
+`--no-stripspace`::
Strip leading and trailing whitespace from the note message.
Also strip out empty lines other than a single line between
paragraphs. Lines starting with `#` will be stripped out
--
2.49.0.780.g892193c3f50
^ permalink raw reply related [flat|nested] 44+ messages in thread* [PATCH v3 4/9] doc: notes: rework --[no-]stripspace
2025-05-27 21:19 ` [PATCH v3 0/9] doc: --stdin on notes and core.commentChar mentions kristofferhaugsbakk
` (2 preceding siblings ...)
2025-05-27 21:19 ` [PATCH v3 3/9] doc: notes: split out options with negated forms kristofferhaugsbakk
@ 2025-05-27 21:19 ` kristofferhaugsbakk
2025-05-27 21:19 ` [PATCH v3 5/9] doc: notes: remove stripspace discussion from other options kristofferhaugsbakk
` (5 subsequent siblings)
9 siblings, 0 replies; 44+ messages in thread
From: kristofferhaugsbakk @ 2025-05-27 21:19 UTC (permalink / raw)
To: git; +Cc: Kristoffer Haugsbakk, Jeff King, Teng Long, D . Ben Knoble
From: Kristoffer Haugsbakk <code@khaugsbakk.name>
Document this option by copying the bullet list from git-stripspace(1).
A bullet list is cleaner when there are this many points to consider.
We also get a more standardized description of the multiple-blank-lines
behavior. Compare the repeating (git-notes(1)):
empty lines other than a single line between paragraphs
With (git-stripspace(1)):
multiple consecutive empty lines
And:
leading [...] whitespace
With:
empty lines from the beginning
Leading whitespace in the form of spaces (indentation) are not removed.
However, empty lines at the start of the message are removed.
Note that we drop the mentions of comment line handling because they are
wrong; this option does not control how lines which can be recognized as
comment lines are handled. Only interactivity controls that:
• Comment lines are stripped after editing interactively
• Lines which could be recognized as comment lines are left alone when
the message is given non-interactively
So it is misleading to document the comment line behavior on
this option.
Further, the text is wrong:
Lines starting with `#` will be stripped out in non-editor cases
like `-m`, [...]
Comment lines are still indirectly discussed on other options. We will
deal with them in the next commit.
Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---
Notes (series):
v2:
• New
• Together with one other other patch replaces v1 patch “doc: notes:
mention comment character configuration”
• I figured out that mentioning the comment character/comment lines
doesn’t make sense here. So all attempts to rephrase “comment
character” or “lines that start with `#`” are gone
Documentation/git-notes.adoc | 12 +++++++-----
1 file changed, 7 insertions(+), 5 deletions(-)
diff --git a/Documentation/git-notes.adoc b/Documentation/git-notes.adoc
index 8706b33f2ee..d672794a942 100644
--- a/Documentation/git-notes.adoc
+++ b/Documentation/git-notes.adoc
@@ -184,11 +184,13 @@ OPTIONS
`--stripspace`::
`--no-stripspace`::
- Strip leading and trailing whitespace from the note message.
- Also strip out empty lines other than a single line between
- paragraphs. Lines starting with `#` will be stripped out
- in non-editor cases like `-m`, `-F` and `-C`, but not in
- editor case like `git notes edit`, `-c`, etc.
+ Clean up whitespace. Specifically (see
+ linkgit:git-stripspace[1]):
++
+- remove trailing whitespace from all lines
+- collapse multiple consecutive empty lines into one empty line
+- remove empty lines from the beginning and end of the input
+- add a missing `\n` to the last line if necessary.
`--ref <ref>`::
Manipulate the notes tree in _<ref>_. This overrides
--
2.49.0.780.g892193c3f50
^ permalink raw reply related [flat|nested] 44+ messages in thread* [PATCH v3 5/9] doc: notes: remove stripspace discussion from other options
2025-05-27 21:19 ` [PATCH v3 0/9] doc: --stdin on notes and core.commentChar mentions kristofferhaugsbakk
` (3 preceding siblings ...)
2025-05-27 21:19 ` [PATCH v3 4/9] doc: notes: rework --[no-]stripspace kristofferhaugsbakk
@ 2025-05-27 21:19 ` kristofferhaugsbakk
2025-05-27 21:19 ` [PATCH v3 6/9] doc: notes: clearly state that --stripspace is the default kristofferhaugsbakk
` (4 subsequent siblings)
9 siblings, 0 replies; 44+ messages in thread
From: kristofferhaugsbakk @ 2025-05-27 21:19 UTC (permalink / raw)
To: git; +Cc: Kristoffer Haugsbakk, Jeff King, Teng Long, D . Ben Knoble
From: Kristoffer Haugsbakk <code@khaugsbakk.name>
Cleaning up whitespace in metadata is typical porcelain behavior and
this default does not need to be pointed out.[1] Only speak up when
the default `--stripspace` is not used.
Also remove all misleading mentions of comment lines in the process;
see the previous commit.
Also remove the period that trails the parenthetical here.
† 1: See `-F` in git-commit(1) which has nothing to say about whitespace
cleanup. The cleanup discussion is on `--cleanup`.
Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---
Notes (series):
v2:
• New
• Together with one other patch replaces v1 patch “doc: notes:
mention comment character configuration”
• I figured out that mentioning the comment character/comment lines
doesn’t make sense here. So all attempts to rephrase “comment
character” or “lines that start with `#`” are gone
Documentation/git-notes.adoc | 12 ++----------
1 file changed, 2 insertions(+), 10 deletions(-)
diff --git a/Documentation/git-notes.adoc b/Documentation/git-notes.adoc
index d672794a942..383e8bca685 100644
--- a/Documentation/git-notes.adoc
+++ b/Documentation/git-notes.adoc
@@ -144,26 +144,18 @@ OPTIONS
Use the given note message (instead of prompting).
If multiple `-m` options are given, their values
are concatenated as separate paragraphs.
- Lines starting with `#` and empty lines other than a
- single line between paragraphs will be stripped out.
- If you wish to keep them verbatim, use `--no-stripspace`.
`-F <file>`::
`--file=<file>`::
Take the note message from the given file. Use `-` to
read the note message from the standard input.
- Lines starting with `#` and empty lines other than a
- single line between paragraphs will be stripped out.
- If you wish to keep them verbatim, use `--no-stripspace`.
`-C <object>`::
`--reuse-message=<object>`::
Take the given blob object (for example, another note) as the
note message. (Use `git notes copy <object>` instead to
- copy notes between objects.). By default, message will be
- copied verbatim, but if you wish to strip out the lines
- starting with `#` and empty lines other than a single line
- between paragraphs, use with `--stripspace` option.
+ copy notes between objects.) Implies `--no-stripspace` since
+ the default behavior is to copy the message verbatim.
`-c <object>`::
`--reedit-message=<object>`::
--
2.49.0.780.g892193c3f50
^ permalink raw reply related [flat|nested] 44+ messages in thread* [PATCH v3 6/9] doc: notes: clearly state that --stripspace is the default
2025-05-27 21:19 ` [PATCH v3 0/9] doc: --stdin on notes and core.commentChar mentions kristofferhaugsbakk
` (4 preceding siblings ...)
2025-05-27 21:19 ` [PATCH v3 5/9] doc: notes: remove stripspace discussion from other options kristofferhaugsbakk
@ 2025-05-27 21:19 ` kristofferhaugsbakk
2025-05-27 21:19 ` [PATCH v3 7/9] doc: notes: point out copy --stdin use with argv kristofferhaugsbakk
` (3 subsequent siblings)
9 siblings, 0 replies; 44+ messages in thread
From: kristofferhaugsbakk @ 2025-05-27 21:19 UTC (permalink / raw)
To: git
Cc: Kristoffer Haugsbakk, Jeff King, Teng Long, D . Ben Knoble,
Junio C Hamano
From: Kristoffer Haugsbakk <code@khaugsbakk.name>
Clearly state when which of the regular and negated form of the
option take effect.[1]
Also mention the subtle behavior that occurs when you mix options like
`-m` and `-C`, including a note that it might be fixed in the future.
The topic was brought up on v8 of the `--separator` series.[2][3]
[1]: https://lore.kernel.org/git/xmqqcyct1mtq.fsf@gitster.g/
[2]: https://lore.kernel.org/git/xmqq4jp326oj.fsf@gitster.g/
† 3: v11 was the version that landed
Helped-by: Junio C Hamano <gitster@pobox.com>
Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---
Notes (series):
v3:
• Mention that it is a bug (“known limitation”) which might be fixed.
Link: https://lore.kernel.org/git/xmqqiklrvwl4.fsf@gitster.g/
• Message: discuss this new “subtle behavior” part
v2:
• New
• The `--` are to prevent the new paragraph from becoming a continuation
of the last bullet point
• Junio pointed out that I didn’t go over the part about checking
which variant (regular or negation) are the default. See the link:
https://lore.kernel.org/git/xmqqcyct1mtq.fsf@gitster.g/
I decided to do this on this series.
Link: https://lore.kernel.org/git/xmqqfrgzhzbp.fsf@gitster.g/
• The last part of the paragraph is based on the commit message of
c4e2aa7d45f (notes.c: introduce "--[no-]stripspace" option,
2023-05-27).
See the review on the patch:
https://lore.kernel.org/git/xmqq4jp326oj.fsf@gitster.g/
There was concern about the order of options:
> ... One more thing need to note is "the order of
> the options matter", [...]
This sounds more like a design/implementation mistake that we may
want to fix.
This new part is supposed to address that.
Documentation/git-notes.adoc | 9 +++++++++
1 file changed, 9 insertions(+)
diff --git a/Documentation/git-notes.adoc b/Documentation/git-notes.adoc
index 383e8bca685..ef5a939516e 100644
--- a/Documentation/git-notes.adoc
+++ b/Documentation/git-notes.adoc
@@ -179,10 +179,19 @@ OPTIONS
Clean up whitespace. Specifically (see
linkgit:git-stripspace[1]):
+
+--
- remove trailing whitespace from all lines
- collapse multiple consecutive empty lines into one empty line
- remove empty lines from the beginning and end of the input
- add a missing `\n` to the last line if necessary.
+--
++
+`--stripspace` is the default except for
+`-C`/`--reuse-message`. However, keep in mind that this depends on the
+order of similar options. For example, for `-C <object> -m<message>`,
+`--stripspace` will be used because the default for `-m` overrides the
+previous `-C`. This is a known limitation that may be fixed in the
+future.
`--ref <ref>`::
Manipulate the notes tree in _<ref>_. This overrides
--
2.49.0.780.g892193c3f50
^ permalink raw reply related [flat|nested] 44+ messages in thread* [PATCH v3 7/9] doc: notes: point out copy --stdin use with argv
2025-05-27 21:19 ` [PATCH v3 0/9] doc: --stdin on notes and core.commentChar mentions kristofferhaugsbakk
` (5 preceding siblings ...)
2025-05-27 21:19 ` [PATCH v3 6/9] doc: notes: clearly state that --stripspace is the default kristofferhaugsbakk
@ 2025-05-27 21:19 ` kristofferhaugsbakk
2025-05-27 21:19 ` [PATCH v3 8/9] doc: notes: treat --stdin equally between copy/remove kristofferhaugsbakk
` (2 subsequent siblings)
9 siblings, 0 replies; 44+ messages in thread
From: kristofferhaugsbakk @ 2025-05-27 21:19 UTC (permalink / raw)
To: git; +Cc: Kristoffer Haugsbakk, Jeff King, Teng Long, D . Ben Knoble
From: Kristoffer Haugsbakk <code@khaugsbakk.name>
Unlike `remove --stdin`, this option cannot be combined with object
names given via the command line.
Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---
Documentation/git-notes.adoc | 3 +++
1 file changed, 3 insertions(+)
diff --git a/Documentation/git-notes.adoc b/Documentation/git-notes.adoc
index ef5a939516e..9ce71ec3455 100644
--- a/Documentation/git-notes.adoc
+++ b/Documentation/git-notes.adoc
@@ -87,6 +87,9 @@ In `--stdin` mode, take lines in the format
on standard input, and copy the notes from each _<from-object>_ to its
corresponding _<to-object>_. (The optional _<rest>_ is ignored so that
the command can read the input given to the `post-rewrite` hook.)
++
+`--stdin` cannot be combined with object names given on the command
+line.
`append`::
Append new message(s) given by `-m` or `-F` options to an
--
2.49.0.780.g892193c3f50
^ permalink raw reply related [flat|nested] 44+ messages in thread* [PATCH v3 8/9] doc: notes: treat --stdin equally between copy/remove
2025-05-27 21:19 ` [PATCH v3 0/9] doc: --stdin on notes and core.commentChar mentions kristofferhaugsbakk
` (6 preceding siblings ...)
2025-05-27 21:19 ` [PATCH v3 7/9] doc: notes: point out copy --stdin use with argv kristofferhaugsbakk
@ 2025-05-27 21:19 ` kristofferhaugsbakk
2025-05-27 21:19 ` [PATCH v3 9/9] doc: notes: use stuck form throughout kristofferhaugsbakk
2025-05-27 22:33 ` [PATCH v3 0/9] doc: --stdin on notes and core.commentChar mentions Junio C Hamano
9 siblings, 0 replies; 44+ messages in thread
From: kristofferhaugsbakk @ 2025-05-27 21:19 UTC (permalink / raw)
To: git; +Cc: Kristoffer Haugsbakk, Jeff King, Teng Long, D . Ben Knoble
From: Kristoffer Haugsbakk <code@khaugsbakk.name>
46538012d94 (notes remove: --stdin reads from the standard input,
2011-05-18) added `--stdin` for the `remove` subcommand, documenting it
in the “Options” section. But `copy --stdin` was added before that, in
160baa0d9cb (notes: implement 'git notes copy --stdin', 2010-03-12).
Treat this option equally between the two subcommands:
• remove: mention `--stdin` on the subcommand as well, like for `copy`
• copy: mention it as well under the option documentation
Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---
Notes (series):
v3:
• Rephrase to “Only valid for”
Link: https://lore.kernel.org/git/xmqqecwfvwdu.fsf@gitster.g/
v2:
• On --stdin: just refer to the respective subcommands and stop there.
As suggested.
Link: https://lore.kernel.org/git/xmqq34czhyz8.fsf@gitster.g/
Documentation/git-notes.adoc | 8 +++++---
1 file changed, 5 insertions(+), 3 deletions(-)
diff --git a/Documentation/git-notes.adoc b/Documentation/git-notes.adoc
index 9ce71ec3455..397f6caa92a 100644
--- a/Documentation/git-notes.adoc
+++ b/Documentation/git-notes.adoc
@@ -127,6 +127,10 @@ When done, the user can either finalize the merge with
giving zero or one object from the command line, this is
equivalent to specifying an empty note message to
the `edit` subcommand.
++
+In `--stdin` mode, also remove the object names given on standard
+input. In other words, `--stdin` can be combined with object names from
+the command line.
`prune`::
Remove all notes for non-existing/unreachable objects.
@@ -208,9 +212,7 @@ future.
object that does not have notes attached to it.
`--stdin`::
- Also read the object names to remove notes from the standard
- input (there is no reason you cannot combine this with object
- names from the command line).
+ Only valid for `remove` and `copy`. See the respective subcommands.
`-n`::
`--dry-run`::
--
2.49.0.780.g892193c3f50
^ permalink raw reply related [flat|nested] 44+ messages in thread* [PATCH v3 9/9] doc: notes: use stuck form throughout
2025-05-27 21:19 ` [PATCH v3 0/9] doc: --stdin on notes and core.commentChar mentions kristofferhaugsbakk
` (7 preceding siblings ...)
2025-05-27 21:19 ` [PATCH v3 8/9] doc: notes: treat --stdin equally between copy/remove kristofferhaugsbakk
@ 2025-05-27 21:19 ` kristofferhaugsbakk
2025-05-27 22:33 ` [PATCH v3 0/9] doc: --stdin on notes and core.commentChar mentions Junio C Hamano
9 siblings, 0 replies; 44+ messages in thread
From: kristofferhaugsbakk @ 2025-05-27 21:19 UTC (permalink / raw)
To: git; +Cc: Kristoffer Haugsbakk, Jeff King, Teng Long, D . Ben Knoble
From: Kristoffer Haugsbakk <code@khaugsbakk.name>
gitcli(7) recommends the *stuck form*. `--ref` is the only one which
does not use it.
Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---
Notes (series):
v2:
• New
• I didn’t spot this in the first round. Hopefully it’s fine to include
it as well while we are editing this file. I would consider making a
separate thread if I wasn’t editing nearby hunks.
Documentation/git-notes.adoc | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/Documentation/git-notes.adoc b/Documentation/git-notes.adoc
index 397f6caa92a..46a232ca718 100644
--- a/Documentation/git-notes.adoc
+++ b/Documentation/git-notes.adoc
@@ -200,7 +200,7 @@ order of similar options. For example, for `-C <object> -m<message>`,
previous `-C`. This is a known limitation that may be fixed in the
future.
-`--ref <ref>`::
+`--ref=<ref>`::
Manipulate the notes tree in _<ref>_. This overrides
`GIT_NOTES_REF` and the `core.notesRef` configuration. The ref
specifies the full refname when it begins with `refs/notes/`; when it
--
2.49.0.780.g892193c3f50
^ permalink raw reply related [flat|nested] 44+ messages in thread* Re: [PATCH v3 0/9] doc: --stdin on notes and core.commentChar mentions
2025-05-27 21:19 ` [PATCH v3 0/9] doc: --stdin on notes and core.commentChar mentions kristofferhaugsbakk
` (8 preceding siblings ...)
2025-05-27 21:19 ` [PATCH v3 9/9] doc: notes: use stuck form throughout kristofferhaugsbakk
@ 2025-05-27 22:33 ` Junio C Hamano
9 siblings, 0 replies; 44+ messages in thread
From: Junio C Hamano @ 2025-05-27 22:33 UTC (permalink / raw)
To: kristofferhaugsbakk
Cc: git, Kristoffer Haugsbakk, Jeff King, Teng Long, D . Ben Knoble
kristofferhaugsbakk@fastmail.com writes:
> From: Kristoffer Haugsbakk <code@khaugsbakk.name>
>
> I wanted to fix `--stdin` in the git-notes(1) documentation. Then I
> found some other things on that doc as well as things to do with
> `core.commentChar`.
Looking really good. Let me mark the topic for 'next'.
Thanks.
^ permalink raw reply [flat|nested] 44+ messages in thread