@matheusbsbs / matheus-bagliano / commits / e136f33b5f
Fork 0

Documentation/config.txt: Document config file syntax better

Separate part of Documentation/config.txt which deals with git config file syntax into "Syntax" subsection, and expand it. Add information about subsections, boolean values, escaping and escape sequences in string values, and continuing variable value on the next line. Add also proxy settings to config file example to show example of partially enclosed in double quotes string value. Parts based on comments by Junio C Hamano, Johannes Schindelin, config.c, and the smb.conf(5) man page. Signed-off-by: Jakub Narebski <jnareb@gmail.com> Signed-off-by: Junio C Hamano <junkio@cox.net>

Jakub Narebski committed Jan 22, 2007 at 16:25 UTC e136f33b5ff9b2293a61073295b0294fad8e6e42
1 file changed +69 -7
Documentation/config.txt
+69 -7
@@ -14,14 +14,72 @@ dot-separated segment and the section name is everything before the last
14 dot. The variable names are case-insensitive and only alphanumeric
15 characters are allowed. Some variables may appear multiple times.
16
17 +Syntax
18 +~~~~~~
19 +
20 The syntax is fairly flexible and permissive; whitespaces are mostly
18 -ignored. The '#' and ';' characters begin comments to the end of line,
19 -blank lines are ignored, lines containing strings enclosed in square
20 -brackets start sections and all the other lines are recognized
21 -as setting variables, in the form 'name = value'. If there is no equal
22 -sign on the line, the entire line is taken as 'name' and the variable
23 -is recognized as boolean "true". String values may be entirely or partially
24 -enclosed in double quotes; some variables may require special value format.
21 +ignored. The '#' and ';' characters begin comments to the end of line,
22 +blank lines are ignored.
23 +
24 +The file consists of sections and variables. A section begins with
25 +the name of the section in square brackets and continues until the next
26 +section begins. Section names are not case sensitive. Only alphanumeric
27 +characters, '`-`' and '`.`' are allowed in section names. Each variable
28 +must belong to some section, which means that there must be section
29 +header before first setting of a variable.
30 +
31 +Sections can be further divided into subsections. To begin a subsection
32 +put its name in double quotes, separated by space from the section name,
33 +in the section header, like in example below:
34 +
35 +--------
36 + [section "subsection"]
37 +
38 +--------
39 +
40 +Subsection names can contain any characters (doublequote '`"`', backslash
41 +'`\`' and newline have to be entered escaped as '`\"`', '`\\`' and '`\n`',
42 +respecitvely) and are case sensitive. Section header cannot span multiple
43 +lines. Variables may belong directly to a section or to a given subsection.
44 +You can have `[section]` if you have `[section "subsection"]`, but you
45 +don't need to.
46 +
47 +There is also (case insensitive) alternative `[section.subsection]` syntax.
48 +In this syntax subsection names follow the same restrictions as for section
49 +name.
50 +
51 +All the other lines are recognized as setting variables, in the form
52 +'name = value'. If there is no equal sign on the line, the entire line
53 +is taken as 'name' and the variable is recognized as boolean "true".
54 +The variable names are case-insensitive and only alphanumeric
55 +characters and '`-`' are allowed. There can be more than one value
56 +for a given variable; we say then that variable is multivalued.
57 +
58 +Leading and trailing whitespace in a variable value is discarded.
59 +Internal whitespace within a variable value is retained verbatim.
60 +
61 +The values following the equals sign in variable assign are all either
62 +a string, an integer, or a boolean. Boolean values may be given as yes/no,
63 +0/1 or true/false. Case is not significant in boolean values, when
64 +converting value to the canonical form using '--bool' type specifier;
65 +`git-repo-config` will ensure that the output is "true" or "false".
66 +
67 +String values may be entirely or partially enclosed in double quotes.
68 +You need to enclose variable value in double quotes if you want to
69 +preserve leading or trailing whitespace, or if variable value contains
70 +beginning of comment characters (if it contains '#' or ';').
71 +Double quote '`"`' and backslash '`\`' characters in variable value must
72 +be escaped: use '`\"`' for '`"`' and '`\\`' for '`\`'.
73 +
74 +The following escape sequences (beside '`\"`' and '`\\`') are recognized:
75 +'`\n`' for newline character (NL), '`\t`' for horizontal tabulation (HT, TAB)
76 +and '`\b`' for backspace (BS). No other char escape sequence, nor octal
77 +char sequences are valid.
78 +
79 +Variable value ending in a '`\`' is continued on the next line in the
80 +customary UNIX fashion.
81 +
82 +Some variables may require special value format.
83
84 Example
85 ~~~~~~~
@@ -40,6 +98,10 @@ Example
98 remote = origin
99 merge = refs/heads/devel
100
101 + # Proxy settings
102 + [core]
103 + gitProxy="ssh" for "ssh://kernel.org/"
104 + gitProxy=default-proxy ; for the rest
105
106 Variables
107 ~~~~~~~~~