doc.go

// Package config implements encoding and decoding of git config files.
//
// 	Configuration File
// 	------------------
//
// 	The Git configuration file contains a number of variables that affect
// 	the Git commands' behavior. The `.git/config` file in each repository
// 	is used to store the configuration for that repository, and
// 	`$HOME/.gitconfig` is used to store a per-user configuration as
// 	fallback values for the `.git/config` file. The file `/etc/gitconfig`
// 	can be used to store a system-wide default configuration.
//
// 	The configuration variables are used by both the Git plumbing
// 	and the porcelains. The variables are divided into sections, wherein
// 	the fully qualified variable name of the variable itself is the last
// 	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; we say then that the variable is
// 	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 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 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.
//
// 	Sections can be further divided into subsections.  To begin a subsection
// 	put its name in double quotes, separated by space from the section name,
// 	in the section header, like in the example below:
//
// 	--------
// 		[section "subsection"]
//
// 	--------
//
// 	Subsection names are case sensitive and can contain any characters except
// 	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.
//
// 	There is also a deprecated `[section.subsection]` syntax. With this
// 	syntax, the subsection name is converted to lower-case and is also
// 	compared case sensitively. These subsection names follow the same
// 	restrictions as section names.
//
// 	All the other lines (and the remainder of the line after the section
// 	header) are recognized as setting variables, in the form
// 	'name = value' (or just 'name', which is a short-hand to say that
// 	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 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.
//
// 	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).  Other char escape sequences (including octal
// 	escape sequences) are invalid.
//
// 	Includes
// 	~~~~~~~~
//
// 	You can include one config file from another by setting the special
// 	`include.path` variable to the name of the file to be included. The
// 	variable takes a pathname as its value, and is subject to tilde
// 	expansion.
//
// 	The included file is expanded immediately, as if its contents had been
// 	found at the location of the include directive. If the value of the
// 	`include.path` variable is a relative path, the path is considered to be
// 	relative to the configuration file in which the include directive was
// 	found.  See below for examples.
//
//
// 	Example
// 	~~~~~~~
//
// 		# Core variables
// 		[core]
// 			; Don't trust file modes
// 			filemode = false
//
// 		# Our diff algorithm
// 		[diff]
// 			external = /usr/local/bin/diff-wrapper
// 			renames = true
//
// 		[branch "devel"]
// 			remote = origin
// 			merge = refs/heads/devel
//
// 		# Proxy settings
// 		[core]
// 			gitProxy="ssh" for "kernel.org"
// 			gitProxy=default-proxy ; for the rest
//
// 		[include]
// 			path = /path/to/foo.inc ; include by absolute path
// 			path = foo ; expand "foo" relative to the current file
// 			path = ~/foo ; expand "foo" in your `$HOME` directory
//
package config