[PATCH v3 6/9] doc: notes: clearly state that --stripspace is the default

From: kristofferhaugsbakk@fastmail.com <kristofferhaugsbakk@fastmail.com>
Date: May 27, 2025, 21:19 UTC
Message-ID: <184cf032abf477eae06cd1b9f44da0ddab27b44e.1748380390.git.code@khaugsbakk.name>
In-Reply-To: <cover.1748380390.git.code@khaugsbakk.name>

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