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