| Message ID | a75a5eb8793f4ae6eb6e7cf0e2fd017471fefd0e.1711001016.git.dsimic@manjaro.org (mailing list archive) |
|---|---|
| State | Accepted |
| Commit | e6895c3f971dc4d60f7a9fac6ef41a6593a37ba9 |
| Headers | show |
| Series | Fix a bug in configuration parsing, and improve tests and documentation | expand |
On Thu, Mar 21, 2024 at 2:06 AM Dragan Simic <dsimic@manjaro.org> wrote: > 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> > Helped-by: Eric Sunshine <sunshine@sunshineco.com> > Signed-off-by: Dragan Simic <dsimic@manjaro.org> > --- > Changes in v5: > - Rewrote the description of whitespace character handling again, > to eliminate ambiguity, as suggested by Eric Sunshine [3][4] > - Extended the improvements to the following paragraph as well, to > tie it all together, and to make it less ambiguous how to include > leading and trailing whitespace characters into configuration > option values, if desired so > diff --git a/Documentation/config.txt b/Documentation/config.txt > @@ -63,16 +64,17 @@ the variable is the boolean "true"). > +Whitespace characters surrounding `name`, `=` and `value` are discarded. > +Internal whitespace characters within 'value' are retained verbatim. > +Comments starting with either `#` or `;` and extending to the end of line > +are discarded. A line that defines a value can be continued to the next > +line by ending it with a backslash (`\`); the backslash and the end-of-line > +characters are discarded. > + > +If `value` needs to contain leading or trailing whitespace characters, > +it must be enclosed in double quotation marks (`"`). Inside double quotation > +marks, double quote (`"`) and backslash (`\`) characters must be escaped: > +use `\"` for `"` and `\\` for `\`. Thanks. I find this discussion clearer than v4. I don't have any further review comments on v5.
On 2024-03-21 07:22, Eric Sunshine wrote: > On Thu, Mar 21, 2024 at 2:06 AM Dragan Simic <dsimic@manjaro.org> > wrote: >> 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> >> Helped-by: Eric Sunshine <sunshine@sunshineco.com> >> Signed-off-by: Dragan Simic <dsimic@manjaro.org> >> --- >> Changes in v5: >> - Rewrote the description of whitespace character handling >> again, >> to eliminate ambiguity, as suggested by Eric Sunshine [3][4] >> - Extended the improvements to the following paragraph as >> well, to >> tie it all together, and to make it less ambiguous how to >> include >> leading and trailing whitespace characters into >> configuration >> option values, if desired so >> diff --git a/Documentation/config.txt b/Documentation/config.txt >> @@ -63,16 +64,17 @@ the variable is the boolean "true"). >> +Whitespace characters surrounding `name`, `=` and `value` are >> discarded. >> +Internal whitespace characters within 'value' are retained verbatim. >> +Comments starting with either `#` or `;` and extending to the end of >> line >> +are discarded. A line that defines a value can be continued to the >> next >> +line by ending it with a backslash (`\`); the backslash and the >> end-of-line >> +characters are discarded. >> + >> +If `value` needs to contain leading or trailing whitespace >> characters, >> +it must be enclosed in double quotation marks (`"`). Inside double >> quotation >> +marks, double quote (`"`) and backslash (`\`) characters must be >> escaped: >> +use `\"` for `"` and `\\` for `\`. > > Thanks. I find this discussion clearer than v4. > > I don't have any further review comments on v5. Great, thanks! I really appreciate your prompt and detailed reviews.
Eric Sunshine <sunshine@sunshineco.com> writes: > Thanks. I find this discussion clearer than v4. > > I don't have any further review comments on v5. Thanks, both. Let's mark it for 'next' then.
On 2024-03-21 23:58, Junio C Hamano wrote: > Eric Sunshine <sunshine@sunshineco.com> writes: > >> Thanks. I find this discussion clearer than v4. >> >> I don't have any further review comments on v5. > > Thanks, both. Let's mark it for 'next' then. Great, thank you.
diff --git a/Documentation/config.txt b/Documentation/config.txt index 782c2bab906c..70b448b13262 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,16 +64,17 @@ 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. - -Inside double quotes, double quote `"` and backslash `\` characters -must be escaped: use `\"` for `"` and `\\` for `\`. +Whitespace characters surrounding `name`, `=` and `value` are discarded. +Internal whitespace characters within 'value' are retained verbatim. +Comments starting with either `#` or `;` and extending to the end of line +are discarded. A line that defines a value can be continued to the next +line by ending it with a backslash (`\`); the backslash and the end-of-line +characters are discarded. + +If `value` needs to contain leading or trailing whitespace characters, +it must be enclosed in double quotation marks (`"`). Inside double quotation +marks, double quote (`"`) and backslash (`\`) characters must be escaped: +use `\"` for `"` and `\\` for `\`. The following escape sequences (beside `\"` and `\\`) are recognized: `\n` for newline character (NL), `\t` for horizontal tabulation (HT, TAB)
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> Helped-by: Eric Sunshine <sunshine@sunshineco.com> Signed-off-by: Dragan Simic <dsimic@manjaro.org> --- Notes: Changes in v5: - Rewrote the description of whitespace character handling again, to eliminate ambiguity, as suggested by Eric Sunshine [3][4] - Extended the improvements to the following paragraph as well, to tie it all together, and to make it less ambiguous how to include leading and trailing whitespace characters into configuration option values, if desired so - Added a Helped-by tag 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/ [3] https://lore.kernel.org/git/CAPig+cSYhYBa0NsvJCOYo4JsWzLJT9rU++U1QKA3jRB6Cptbhw@mail.gmail.com/ [4] https://lore.kernel.org/git/fdaec126df16bf6fe1c1fca9698f7dcc@manjaro.org/ Documentation/config.txt | 28 +++++++++++++++------------- 1 file changed, 15 insertions(+), 13 deletions(-)