Debian Codegraph @

plumbing/format/config/doc.go

raw
1 // Package config implements encoding and decoding of git config files.
2 //
3 // Configuration File
4 // ------------------
5 //
6 // The Git configuration file contains a number of variables that affect
7 // the Git commands' behavior. The `.git/config` file in each repository
8 // is used to store the configuration for that repository, and
9 // `$HOME/.gitconfig` is used to store a per-user configuration as
10 // fallback values for the `.git/config` file. The file `/etc/gitconfig`
11 // can be used to store a system-wide default configuration.
12 //
13 // The configuration variables are used by both the Git plumbing
14 // and the porcelains. The variables are divided into sections, wherein
15 // the fully qualified variable name of the variable itself is the last
16 // dot-separated segment and the section name is everything before the last
17 // dot. The variable names are case-insensitive, allow only alphanumeric
18 // characters and `-`, and must start with an alphabetic character. Some
19 // variables may appear multiple times; we say then that the variable is
20 // multivalued.
21 //
22 // Syntax
23 // ~~~~~~
24 //
25 // The syntax is fairly flexible and permissive; whitespaces are mostly
26 // ignored. The '#' and ';' characters begin comments to the end of line,
27 // blank lines are ignored.
28 //
29 // The file consists of sections and variables. A section begins with
30 // the name of the section in square brackets and continues until the next
31 // section begins. Section names are case-insensitive. Only alphanumeric
32 // characters, `-` and `.` are allowed in section names. Each variable
33 // must belong to some section, which means that there must be a section
34 // header before the first setting of a variable.
35 //
36 // Sections can be further divided into subsections. To begin a subsection
37 // put its name in double quotes, separated by space from the section name,
38 // in the section header, like in the example below:
39 //
40 // --------
41 // [section "subsection"]
42 //
43 // --------
44 //
45 // Subsection names are case sensitive and can contain any characters except
46 // newline (doublequote `"` and backslash can be included by escaping them
47 // as `\"` and `\\`, respectively). Section headers cannot span multiple
48 // lines. Variables may belong directly to a section or to a given subsection.
49 // You can have `[section]` if you have `[section "subsection"]`, but you
50 // don't need to.
51 //
52 // There is also a deprecated `[section.subsection]` syntax. With this
53 // syntax, the subsection name is converted to lower-case and is also
54 // compared case sensitively. These subsection names follow the same
55 // restrictions as section names.
56 //
57 // All the other lines (and the remainder of the line after the section
58 // header) are recognized as setting variables, in the form
59 // 'name = value' (or just 'name', which is a short-hand to say that
60 // the variable is the boolean "true").
61 // The variable names are case-insensitive, allow only alphanumeric characters
62 // and `-`, and must start with an alphabetic character.
63 //
64 // A line that defines a value can be continued to the next line by
65 // ending it with a `\`; the backquote and the end-of-line are
66 // stripped. Leading whitespaces after 'name =', the remainder of the
67 // line after the first comment character '#' or ';', and trailing
68 // whitespaces of the line are discarded unless they are enclosed in
69 // double quotes. Internal whitespaces within the value are retained
70 // verbatim.
71 //
72 // Inside double quotes, double quote `"` and backslash `\` characters
73 // must be escaped: use `\"` for `"` and `\\` for `\`.
74 //
75 // The following escape sequences (beside `\"` and `\\`) are recognized:
76 // `\n` for newline character (NL), `\t` for horizontal tabulation (HT, TAB)
77 // and `\b` for backspace (BS). Other char escape sequences (including octal
78 // escape sequences) are invalid.
79 //
80 // Includes
81 // ~~~~~~~~
82 //
83 // You can include one config file from another by setting the special
84 // `include.path` variable to the name of the file to be included. The
85 // variable takes a pathname as its value, and is subject to tilde
86 // expansion.
87 //
88 // The included file is expanded immediately, as if its contents had been
89 // found at the location of the include directive. If the value of the
90 // `include.path` variable is a relative path, the path is considered to be
91 // relative to the configuration file in which the include directive was
92 // found. See below for examples.
93 //
94 //
95 // Example
96 // ~~~~~~~
97 //
98 // # Core variables
99 // [core]
100 // ; Don't trust file modes
101 // filemode = false
102 //
103 // # Our diff algorithm
104 // [diff]
105 // external = /usr/local/bin/diff-wrapper
106 // renames = true
107 //
108 // [branch "devel"]
109 // remote = origin
110 // merge = refs/heads/devel
111 //
112 // # Proxy settings
113 // [core]
114 // gitProxy="ssh" for "kernel.org"
115 // gitProxy=default-proxy ; for the rest
116 //
117 // [include]
118 // path = /path/to/foo.inc ; include by absolute path
119 // path = foo ; expand "foo" relative to the current file
120 // path = ~/foo ; expand "foo" in your `$HOME` directory
121 //
122 package config