doc: notes: clearly state that --stripspace is the default

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>
Signed-off-by: Junio C Hamano <gitster@pobox.com>

diff --git a/Documentation/git-notes.adoc b/Documentation/git-notes.adoc
index 383e8bca685285efaa56e9408cacfaeef3f9ca45..ef5a939516e11658aea3a391ce0742c1deaaf796 100644 (file)
--- 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