From: Kristoffer Haugsbakk <code@xxxxxxxxxxxxxxx>
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@xxxxxxxxx>
Signed-off-by: Kristoffer Haugsbakk <code@xxxxxxxxxxxxxxx>
## 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
