dot-separated segment and the section name is everything before the last
dot. The variable names are case-insensitive, allow only alphanumeric
characters and `-`, and must start with an alphabetic character. Some
-variables may appear multiple times.
+variables may appear multiple times; we say then that the variable is
+multivalued.
Syntax
~~~~~~
The file consists of sections and variables. A section begins with
the name of the section in square brackets and continues until the next
-section begins. Section names are not case sensitive. Only alphanumeric
+section begins. Section names are case-insensitive. Only alphanumeric
characters, `-` and `.` are allowed in section names. Each variable
must belong to some section, which means that there must be a section
header before the first setting of a variable.
--------
Subsection names are case sensitive and can contain any characters except
-newline (doublequote `"` and backslash have to be escaped as `\"` and `\\`,
-respectively). Section headers cannot span multiple
+newline (doublequote `"` and backslash can be included by escaping them
+as `\"` and `\\`, respectively). Section headers cannot span multiple
lines. Variables may belong directly to a section or to a given subsection.
You can have `[section]` if you have `[section "subsection"]`, but you
don't need to.
'name = value'. If there is no equal sign on the line, the entire line
is taken as 'name' and the variable is recognized as boolean "true".
The variable names are case-insensitive, allow only alphanumeric characters
-and `-`, and must start with an alphabetic character. There can be more
-than one value for a given variable; we say then that the variable is
-multivalued.
+and `-`, and must start with an alphabetic character.
-Leading and trailing whitespace in a variable value is discarded.
-Internal whitespace within a variable value is retained verbatim.
+A line that defines a value can be continued to the next line by
+ending it with a `\`; the backquote 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.
-The values following the equals sign in variable assign are all either
-a string, an integer, or a boolean. Boolean values may be given as yes/no,
-1/0, true/false or on/off. Case is not significant in boolean values, when
-converting value to the canonical form using '--bool' type specifier;
-'git config' will ensure that the output is "true" or "false".
-
-String values may be entirely or partially enclosed in double quotes.
-You need to enclose variable values in double quotes if you want to
-preserve leading or trailing whitespace, or if the variable value contains
-comment characters (i.e. it contains '#' or ';').
-Double quote `"` and backslash `\` characters in variable values must
-be escaped: use `\"` for `"` and `\\` for `\`.
+Inside double quotes, 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)
and `\b` for backspace (BS). No other char escape sequence, nor octal
char sequences are valid.
-Variable values ending in a `\` are continued on the next line in the
-customary UNIX fashion.
-
-Some variables may require a special value format.
Includes
~~~~~~~~
path = foo ; expand "foo" relative to the current file
path = ~/foo ; expand "foo" in your $HOME directory
+
+Values
+~~~~~~
+
+Values of many variables are treated as a simple string, but there
+are variables that take values of specific types and there are rules
+as to how to spell them.
+
+boolean::
+
+ When a variable is said to take a boolean value, many
+ synonyms are accepted for 'true' and 'false'; these are all
+ case-insensitive.
+
+ true;; Boolean true can be spelled as `yes`, `on`, `true`,
+ or `1`. Also, a variable defined without `= <value>`
+ is taken as true.
+
+ false;; Boolean false can be spelled as `no`, `off`,
+ `false`, or `0`.
++
+When converting value to the canonical form using '--bool' type
+specifier; 'git config' will ensure that the output is "true" or
+"false" (spelled in lowercase).
+
+integer::
+ The value for many variables that specify various sizes can
+ be suffixed with `k`, `M`,... to mean "scale the number by
+ 1024", "by 1024x1024", etc.
+
+
Variables
~~~~~~~~~