From: Dragan Simic <dsimic@manjaro.org>
To: git@vger.kernel.org
Cc: gitster@pobox.com, rsbecker@nexbridge.com, github@seichter.de,
sunshine@sunshineco.com
Subject: [PATCH v4 4/4] config.txt: describe handling of whitespace further
Date: Thu, 21 Mar 2024 05:17:43 +0100 [thread overview]
Message-ID: <f84c5e8e4a90be3f9fe3cc853e0d40aed4e58826.1710994548.git.dsimic@manjaro.org> (raw)
In-Reply-To: <cover.1710994548.git.dsimic@manjaro.org>
Make it more clear what the whitespace characters are in the context of git
configuration files, and significantly improve the description of the leading
and trailing whitespace handling, especially how it works out together with
the presence of inline comments.
Helped-by: Junio C Hamano <gitster@pobox.com>
Signed-off-by: Dragan Simic <dsimic@manjaro.org>
---
Notes:
Changes in v4:
- Improved the wording and accuracy of the description of whitespace
character handling, as discussed with Junio, [1][2] by taking a more
radical approach and rewriting an entire paragraph, because it has
reached the point where "patching the patchwork" no longer worked;
I'm quite happy with the way it turned out this time
- Expanded the patch description a tiny bit
- Added a Helped-by tag
Changes in v3:
- Patch description was expanded a bit, to make it more on point
- No changes to the documentation were introduced
Changes in v2:
- No changes were introduced
[1] https://lore.kernel.org/git/xmqqttl1js1o.fsf@gitster.g/
[2] https://lore.kernel.org/git/ce041191a245ff888b1710cdcaad9e61@manjaro.org/
Documentation/config.txt | 21 ++++++++++++---------
1 file changed, 12 insertions(+), 9 deletions(-)
diff --git a/Documentation/config.txt b/Documentation/config.txt
index 782c2bab906c..9d4e99393530 100644
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -22,9 +22,10 @@ multivalued.
Syntax
~~~~~~
-The syntax is fairly flexible and permissive; whitespaces are mostly
-ignored. The '#' and ';' characters begin comments to the end of line,
-blank lines are ignored.
+The syntax is fairly flexible and permissive. Whitespace characters,
+which in this context are the space character (SP) and the horizontal
+tabulation (HT), are mostly ignored. The '#' and ';' characters begin
+comments to the end of line. Blank lines are ignored.
The file consists of sections and variables. A section begins with
the name of the section in square brackets and continues until the next
@@ -63,13 +64,15 @@ the variable is the boolean "true").
The variable names are case-insensitive, allow only alphanumeric characters
and `-`, and must start with an alphabetic character.
+
A line that defines a value can be continued to the next line by
-ending it with a `\`; the backslash and the end-of-line are
-stripped. Leading whitespaces after 'name =', the remainder of the
-line after the first comment character '#' or ';', and trailing
-whitespaces of the line are discarded unless they are enclosed in
-double quotes. Internal whitespaces within the value are retained
-verbatim.
+ending it with a `\`; the backslash and the end-of-line are stripped.
+Leading whitespace characters before 'name =' are discarded.
+The portion of the line after the first comment character, including
+the comment character itself, is discarded. Unless enclosed in double
+quotation marks (`"`), any leading or trailing whitespace characters
+surrounding 'value' are discarded. Internal whitespace characters
+within 'value' are retained verbatim.
Inside double quotes, double quote `"` and backslash `\` characters
must be escaped: use `\"` for `"` and `\\` for `\`.
next prev parent reply other threads:[~2024-03-21 4:17 UTC|newest]
Thread overview: 14+ messages / expand[flat|nested] mbox.gz Atom feed top
2024-03-21 4:17 [PATCH v4 0/4] Fix a bug in configuration parsing, and improve tests and documentation Dragan Simic
2024-03-21 4:17 ` [PATCH v4 1/4] config: minor addition of whitespace Dragan Simic
2024-03-21 4:17 ` [PATCH v4 2/4] config: really keep value-internal whitespace verbatim Dragan Simic
2024-03-21 4:17 ` [PATCH v4 3/4] t1300: add more tests for whitespace and inline comments Dragan Simic
2024-03-21 4:55 ` Eric Sunshine
2024-03-21 5:01 ` Dragan Simic
2024-03-21 4:17 ` Dragan Simic [this message]
2024-03-21 5:11 ` [PATCH v4 4/4] config.txt: describe handling of whitespace further Eric Sunshine
2024-03-21 5:16 ` Dragan Simic
2024-03-21 5:21 ` Eric Sunshine
2024-03-21 5:31 ` Dragan Simic
2024-03-21 7:32 ` Junio C Hamano
2024-03-21 4:50 ` [PATCH v4 0/4] Fix a bug in configuration parsing, and improve tests and documentation Eric Sunshine
2024-03-21 4:58 ` Dragan Simic
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=f84c5e8e4a90be3f9fe3cc853e0d40aed4e58826.1710994548.git.dsimic@manjaro.org \
--to=dsimic@manjaro.org \
--cc=git@vger.kernel.org \
--cc=github@seichter.de \
--cc=gitster@pobox.com \
--cc=rsbecker@nexbridge.com \
--cc=sunshine@sunshineco.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.