]> Kevux Git Server - rit/commit
signature-format.txt: explain and illustrate multi-line headers
authorJunio C Hamano <gitster@pobox.com>
Wed, 13 Oct 2021 02:06:01 +0000 (19:06 -0700)
committerJunio C Hamano <gitster@pobox.com>
Wed, 13 Oct 2021 02:06:24 +0000 (19:06 -0700)
commitf6c013dfa1a002661543ad5504a918636099c91b
tree6e308b44cb89aa4c4742216d3ab7b7693b57ee19
parent225bc32a989d7a22fa6addafd4ce7dcd04675dbf
signature-format.txt: explain and illustrate multi-line headers

A signature attached to a signed commit, and the contents of the
commit that merged a signed tag, are both recorded as a value of an
object header field as a multi-line value, and are subject to the
formatting convention for multi-line values in the headers, with a
leading SP signaling that the rest of the line is a continuation of
the previous line.  Most notably, an empty line in such a multi-line
value would result in a line with a sole SP on it.

Examples in the signature-format technical documentation include a
few of these cases but we did not show these otherwise invisible SPs
in the example.  These trailing spaces cannot be seen on display or
on paper, and forces the readers to look for them in their editors
or pagers, even if we added them to the document.

Extend the overview section to explain the multi-line value
formatting and highlight these otherwise invisible SPs by inventing
the "a dollar-sign at the end of line that appears after SP merely
signals that there is a SP there, and the dollar-sign itself does
not appear in the real file" notation, inspired by "cat -e" output,
to help readers to learn exactly where such "a single SP that is
originally an empty line" appears in the examples.

Reported-by: Rob Browning <rlb@defaultvalue.org>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Documentation/technical/signature-format.txt