| 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 |