diff options
Diffstat (limited to 'Documentation/git-config.adoc')
| -rw-r--r-- | Documentation/git-config.adoc | 654 |
1 files changed, 654 insertions, 0 deletions
diff --git a/Documentation/git-config.adoc b/Documentation/git-config.adoc new file mode 100644 index 0000000000..511b2e26bf --- /dev/null +++ b/Documentation/git-config.adoc @@ -0,0 +1,654 @@ +git-config(1) +============= + +NAME +---- +git-config - Get and set repository or global options + + +SYNOPSIS +-------- +[verse] +'git config list' [<file-option>] [<display-option>] [--includes] +'git config get' [<file-option>] [<display-option>] [--includes] [--all] [--regexp] [--value=<pattern>] [--fixed-value] [--default=<default>] [--url=<url>] <name> +'git config set' [<file-option>] [--type=<type>] [--all] [--value=<pattern>] [--fixed-value] <name> <value> +'git config unset' [<file-option>] [--all] [--value=<pattern>] [--fixed-value] <name> +'git config rename-section' [<file-option>] <old-name> <new-name> +'git config remove-section' [<file-option>] <name> +'git config edit' [<file-option>] +'git config' [<file-option>] --get-colorbool <name> [<stdout-is-tty>] + +DESCRIPTION +----------- +You can query/set/replace/unset options with this command. The name is +actually the section and the key separated by a dot, and the value will be +escaped. + +Multiple lines can be added to an option by using the `--append` option. +If you want to update or unset an option which can occur on multiple +lines, `--value=<pattern>` (which is an extended regular expression, +unless the `--fixed-value` option is given) needs to be given. Only the +existing values that match the pattern are updated or unset. If +you want to handle the lines that do *not* match the pattern, just +prepend a single exclamation mark in front (see also <<EXAMPLES>>), +but note that this only works when the `--fixed-value` option is not +in use. + +The `--type=<type>` option instructs 'git config' to ensure that incoming and +outgoing values are canonicalize-able under the given <type>. If no +`--type=<type>` is given, no canonicalization will be performed. Callers may +unset an existing `--type` specifier with `--no-type`. + +When reading, the values are read from the system, global and +repository local configuration files by default, and options +`--system`, `--global`, `--local`, `--worktree` and +`--file <filename>` can be used to tell the command to read from only +that location (see <<FILES>>). + +When writing, the new value is written to the repository local +configuration file by default, and options `--system`, `--global`, +`--worktree`, `--file <filename>` can be used to tell the command to +write to that location (you can say `--local` but that is the +default). + +This command will fail with non-zero status upon error. Some exit +codes are: + +- The section or key is invalid (ret=1), +- no section or name was provided (ret=2), +- the config file is invalid (ret=3), +- the config file cannot be written (ret=4), +- you try to unset an option which does not exist (ret=5), +- you try to unset/set an option for which multiple lines match (ret=5), or +- you try to use an invalid regexp (ret=6). + +On success, the command returns the exit code 0. + +A list of all available configuration variables can be obtained using the +`git help --config` command. + +COMMANDS +-------- + +list:: + List all variables set in config file, along with their values. + +get:: + Emits the value of the specified key. If key is present multiple times + in the configuration, emits the last value. If `--all` is specified, + emits all values associated with key. Returns error code 1 if key is + not present. + +set:: + Set value for one or more config options. By default, this command + refuses to write multi-valued config options. Passing `--all` will + replace all multi-valued config options with the new value, whereas + `--value=` will replace all config options whose values match the given + pattern. + +unset:: + Unset value for one or more config options. By default, this command + refuses to unset multi-valued keys. Passing `--all` will unset all + multi-valued config options, whereas `--value` will unset all config + options whose values match the given pattern. + +rename-section:: + Rename the given section to a new name. + +remove-section:: + Remove the given section from the configuration file. + +edit:: + Opens an editor to modify the specified config file; either + `--system`, `--global`, `--local` (default), `--worktree`, or + `--file <config-file>`. + +[[OPTIONS]] +OPTIONS +------- + +--replace-all:: + Default behavior is to replace at most one line. This replaces + all lines matching the key (and optionally `--value=<pattern>`). + +--append:: + Adds a new line to the option without altering any existing + values. This is the same as providing '--value=^$' in `set`. + +--comment <message>:: + Append a comment at the end of new or modified lines. + + If _<message>_ begins with one or more whitespaces followed + by "#", it is used as-is. If it begins with "#", a space is + prepended before it is used. Otherwise, a string " # " (a + space followed by a hash followed by a space) is prepended + to it. And the resulting string is placed immediately after + the value defined for the variable. The _<message>_ must + not contain linefeed characters (no multi-line comments are + permitted). + +--all:: + With `get`, return all values for a multi-valued key. + +--regexp:: + With `get`, interpret the name as a regular expression. Regular + expression matching is currently case-sensitive and done against a + canonicalized version of the key in which section and variable names + are lowercased, but subsection names are not. + +--url=<URL>:: + When given a two-part <name> as <section>.<key>, the value for + <section>.<URL>.<key> whose <URL> part matches the best to the + given URL is returned (if no such key exists, the value for + <section>.<key> is used as a fallback). When given just the + <section> as name, do so for all the keys in the section and + list them. Returns error code 1 if no value is found. + +--global:: + For writing options: write to global `~/.gitconfig` file + rather than the repository `.git/config`, write to + `$XDG_CONFIG_HOME/git/config` file if this file exists and the + `~/.gitconfig` file doesn't. ++ +For reading options: read only from global `~/.gitconfig` and from +`$XDG_CONFIG_HOME/git/config` rather than from all available files. ++ +See also <<FILES>>. + +--system:: + For writing options: write to system-wide + `$(prefix)/etc/gitconfig` rather than the repository + `.git/config`. ++ +For reading options: read only from system-wide `$(prefix)/etc/gitconfig` +rather than from all available files. ++ +See also <<FILES>>. + +--local:: + For writing options: write to the repository `.git/config` file. + This is the default behavior. ++ +For reading options: read only from the repository `.git/config` rather than +from all available files. ++ +See also <<FILES>>. + +--worktree:: + Similar to `--local` except that `$GIT_DIR/config.worktree` is + read from or written to if `extensions.worktreeConfig` is + enabled. If not it's the same as `--local`. Note that `$GIT_DIR` + is equal to `$GIT_COMMON_DIR` for the main working tree, but is of + the form `$GIT_DIR/worktrees/<id>/` for other working trees. See + linkgit:git-worktree[1] to learn how to enable + `extensions.worktreeConfig`. + +-f <config-file>:: +--file <config-file>:: + For writing options: write to the specified file rather than the + repository `.git/config`. ++ +For reading options: read only from the specified file rather than from all +available files. ++ +See also <<FILES>>. + +--blob <blob>:: + Similar to `--file` but use the given blob instead of a file. E.g. + you can use 'master:.gitmodules' to read values from the file + '.gitmodules' in the master branch. See "SPECIFYING REVISIONS" + section in linkgit:gitrevisions[7] for a more complete list of + ways to spell blob names. + +`--value=<pattern>`:: +`--no-value`:: + With `get`, `set`, and `unset`, match only against + _<pattern>_. The pattern is an extended regular expression unless + `--fixed-value` is given. ++ +Use `--no-value` to unset _<pattern>_. + +--fixed-value:: + When used with `--value=<pattern>`, treat _<pattern>_ as + an exact string instead of a regular expression. This will restrict + the name/value pairs that are matched to only those where the value + is exactly equal to _<pattern>_. + +--type <type>:: + 'git config' will ensure that any input or output is valid under the given + type constraint(s), and will canonicalize outgoing values in `<type>`'s + canonical form. ++ +Valid `<type>`'s include: ++ +- 'bool': canonicalize values `true`, `yes`,`on`, and positive + numbers as "true", and values `false`, `no`, `off` and `0` as + "false". +- 'int': canonicalize values as simple decimal numbers. An optional suffix of + 'k', 'm', or 'g' will cause the value to be multiplied by 1024, 1048576, or + 1073741824 upon input. +- 'bool-or-int': canonicalize according to either 'bool' or 'int', as described + above. +- 'path': canonicalize by expanding a leading `~` to the value of `$HOME` and + `~user` to the home directory for the specified user. This specifier has no + effect when setting the value (but you can use `git config section.variable + ~/` from the command line to let your shell do the expansion.) +- 'expiry-date': canonicalize by converting from a fixed or relative date-string + to a timestamp. This specifier has no effect when setting the value. +- 'color': When getting a value, canonicalize by converting to an ANSI color + escape sequence. When setting a value, a sanity-check is performed to ensure + that the given value is canonicalize-able as an ANSI color, but it is written + as-is. ++ + +--bool:: +--int:: +--bool-or-int:: +--path:: +--expiry-date:: + Historical options for selecting a type specifier. Prefer instead `--type` + (see above). + +--no-type:: + Un-sets the previously set type specifier (if one was previously set). This + option requests that 'git config' not canonicalize the retrieved variable. + `--no-type` has no effect without `--type=<type>` or `--<type>`. + +-z:: +--null:: + For all options that output values and/or keys, always + end values with the null character (instead of a + newline). Use newline instead as a delimiter between + key and value. This allows for secure parsing of the + output without getting confused e.g. by values that + contain line breaks. + +--name-only:: + Output only the names of config variables for `list` or + `get`. + +`--show-names`:: +`--no-show-names`:: + With `get`, show config keys in addition to their values. The + default is `--no-show-names` unless `--url` is given and there + are no subsections in _<name>_. + +--show-origin:: + Augment the output of all queried config options with the + origin type (file, standard input, blob, command line) and + the actual origin (config file path, ref, or blob id if + applicable). + +--show-scope:: + Similar to `--show-origin` in that it augments the output of + all queried config options with the scope of that value + (worktree, local, global, system, command). + +--get-colorbool <name> [<stdout-is-tty>]:: + + Find the color setting for `<name>` (e.g. `color.diff`) and output + "true" or "false". `<stdout-is-tty>` should be either "true" or + "false", and is taken into account when configuration says + "auto". If `<stdout-is-tty>` is missing, then checks the standard + output of the command itself, and exits with status 0 if color + is to be used, or exits with status 1 otherwise. + When the color setting for `name` is undefined, the command uses + `color.ui` as fallback. + +--[no-]includes:: + Respect `include.*` directives in config files when looking up + values. Defaults to `off` when a specific file is given (e.g., + using `--file`, `--global`, etc) and `on` when searching all + config files. + +--default <value>:: + When using `get`, and the requested variable is not found, behave as if + <value> were the value assigned to that variable. + +DEPRECATED MODES +---------------- + +The following modes have been deprecated in favor of subcommands. It is +recommended to migrate to the new syntax. + +'git config <name>':: + Replaced by `git config get <name>`. + +'git config <name> <value> [<value-pattern>]':: + Replaced by `git config set [--value=<pattern>] <name> <value>`. + +-l:: +--list:: + Replaced by `git config list`. + +--get <name> [<value-pattern>]:: + Replaced by `git config get [--value=<pattern>] <name>`. + +--get-all <name> [<value-pattern>]:: + Replaced by `git config get [--value=<pattern>] --all <name>`. + +--get-regexp <name-regexp>:: + Replaced by `git config get --all --show-names --regexp <name-regexp>`. + +--get-urlmatch <name> <URL>:: + Replaced by `git config get --all --show-names --url=<URL> <name>`. + +--get-color <name> [<default>]:: + Replaced by `git config get --type=color [--default=<default>] <name>`. + +--add <name> <value>:: + Replaced by `git config set --append <name> <value>`. + +--unset <name> [<value-pattern>]:: + Replaced by `git config unset [--value=<pattern>] <name>`. + +--unset-all <name> [<value-pattern>]:: + Replaced by `git config unset [--value=<pattern>] --all <name>`. + +--rename-section <old-name> <new-name>:: + Replaced by `git config rename-section <old-name> <new-name>`. + +--remove-section <name>:: + Replaced by `git config remove-section <name>`. + +-e:: +--edit:: + Replaced by `git config edit`. + +CONFIGURATION +------------- +`pager.config` is only respected when listing configuration, i.e., when +using `list` or `get` which may return multiple results. The default is to use +a pager. + +[[FILES]] +FILES +----- + +By default, 'git config' will read configuration options from multiple +files: + +$(prefix)/etc/gitconfig:: + System-wide configuration file. + +$XDG_CONFIG_HOME/git/config:: +~/.gitconfig:: + User-specific configuration files. When the XDG_CONFIG_HOME environment + variable is not set or empty, $HOME/.config/ is used as + $XDG_CONFIG_HOME. ++ +These are also called "global" configuration files. If both files exist, both +files are read in the order given above. + +$GIT_DIR/config:: + Repository specific configuration file. + +$GIT_DIR/config.worktree:: + This is optional and is only searched when + `extensions.worktreeConfig` is present in $GIT_DIR/config. + +You may also provide additional configuration parameters when running any +git command by using the `-c` option. See linkgit:git[1] for details. + +Options will be read from all of these files that are available. If the +global or the system-wide configuration files are missing or unreadable they +will be ignored. If the repository configuration file is missing or unreadable, +'git config' will exit with a non-zero error code. An error message is produced +if the file is unreadable, but not if it is missing. + +The files are read in the order given above, with last value found taking +precedence over values read earlier. When multiple values are taken then all +values of a key from all files will be used. + +By default, options are only written to the repository specific +configuration file. Note that this also affects options like `set` +and `unset`. *'git config' will only ever change one file at a time*. + +You can limit which configuration sources are read from or written to by +specifying the path of a file with the `--file` option, or by specifying a +configuration scope with `--system`, `--global`, `--local`, or `--worktree`. +For more, see <<OPTIONS>> above. + +[[SCOPES]] +SCOPES +------ + +Each configuration source falls within a configuration scope. The scopes +are: + +system:: + $(prefix)/etc/gitconfig + +global:: + $XDG_CONFIG_HOME/git/config ++ +~/.gitconfig + +local:: + $GIT_DIR/config + +worktree:: + $GIT_DIR/config.worktree + +command:: + GIT_CONFIG_{COUNT,KEY,VALUE} environment variables (see <<ENVIRONMENT>> + below) ++ +the `-c` option + +With the exception of 'command', each scope corresponds to a command line +option: `--system`, `--global`, `--local`, `--worktree`. + +When reading options, specifying a scope will only read options from the +files within that scope. When writing options, specifying a scope will write +to the files within that scope (instead of the repository specific +configuration file). See <<OPTIONS>> above for a complete description. + +Most configuration options are respected regardless of the scope it is +defined in, but some options are only respected in certain scopes. See the +respective option's documentation for the full details. + +Protected configuration +~~~~~~~~~~~~~~~~~~~~~~~ + +Protected configuration refers to the 'system', 'global', and 'command' scopes. +For security reasons, certain options are only respected when they are +specified in protected configuration, and ignored otherwise. + +Git treats these scopes as if they are controlled by the user or a trusted +administrator. This is because an attacker who controls these scopes can do +substantial harm without using Git, so it is assumed that the user's environment +protects these scopes against attackers. + +[[ENVIRONMENT]] +ENVIRONMENT +----------- + +GIT_CONFIG_GLOBAL:: +GIT_CONFIG_SYSTEM:: + Take the configuration from the given files instead from global or + system-level configuration. See linkgit:git[1] for details. + +GIT_CONFIG_NOSYSTEM:: + Whether to skip reading settings from the system-wide + $(prefix)/etc/gitconfig file. See linkgit:git[1] for details. + +See also <<FILES>>. + +GIT_CONFIG_COUNT:: +GIT_CONFIG_KEY_<n>:: +GIT_CONFIG_VALUE_<n>:: + If GIT_CONFIG_COUNT is set to a positive number, all environment pairs + GIT_CONFIG_KEY_<n> and GIT_CONFIG_VALUE_<n> up to that number will be + added to the process's runtime configuration. The config pairs are + zero-indexed. Any missing key or value is treated as an error. An empty + GIT_CONFIG_COUNT is treated the same as GIT_CONFIG_COUNT=0, namely no + pairs are processed. These environment variables will override values + in configuration files, but will be overridden by any explicit options + passed via `git -c`. ++ +This is useful for cases where you want to spawn multiple git commands +with a common configuration but cannot depend on a configuration file, +for example when writing scripts. + +GIT_CONFIG:: + If no `--file` option is provided to `git config`, use the file + given by `GIT_CONFIG` as if it were provided via `--file`. This + variable has no effect on other Git commands, and is mostly for + historical compatibility; there is generally no reason to use it + instead of the `--file` option. + +[[EXAMPLES]] +EXAMPLES +-------- + +Given a .git/config like this: + +------------ +# +# This is the config file, and +# a '#' or ';' character indicates +# a comment +# + +; core variables +[core] + ; Don't trust file modes + filemode = false + +; Our diff algorithm +[diff] + external = /usr/local/bin/diff-wrapper + renames = true + +; Proxy settings +[core] + gitproxy=proxy-command for kernel.org + gitproxy=default-proxy ; for all the rest + +; HTTP +[http] + sslVerify +[http "https://weak.example.com"] + sslVerify = false + cookieFile = /tmp/cookie.txt +------------ + +you can set the filemode to true with + +------------ +% git config set core.filemode true +------------ + +The hypothetical proxy command entries actually have a postfix to discern +what URL they apply to. Here is how to change the entry for kernel.org +to "ssh". + +------------ +% git config set --value='for kernel.org$' core.gitproxy '"ssh" for kernel.org' +------------ + +This makes sure that only the key/value pair for kernel.org is replaced. + +To delete the entry for renames, do + +------------ +% git config unset diff.renames +------------ + +If you want to delete an entry for a multivar (like core.gitproxy above), +you have to provide a regex matching the value of exactly one line. + +To query the value for a given key, do + +------------ +% git config get core.filemode +------------ + +or, to query a multivar: + +------------ +% git config get --value="for kernel.org$" core.gitproxy +------------ + +If you want to know all the values for a multivar, do: + +------------ +% git config get --all --show-names core.gitproxy +------------ + +If you like to live dangerously, you can replace *all* core.gitproxy by a +new one with + +------------ +% git config set --all core.gitproxy ssh +------------ + +However, if you really only want to replace the line for the default proxy, +i.e. the one without a "for ..." postfix, do something like this: + +------------ +% git config set --value='! for ' core.gitproxy ssh +------------ + +To actually match only values with an exclamation mark, you have to + +------------ +% git config set --value='[!]' section.key value +------------ + +To add a new proxy, without altering any of the existing ones, use + +------------ +% git config set --append core.gitproxy '"proxy-command" for example.com' +------------ + +An example to use customized color from the configuration in your +script: + +------------ +#!/bin/sh +WS=$(git config get --type=color --default="blue reverse" color.diff.whitespace) +RESET=$(git config get --type=color --default="reset" "") +echo "${WS}your whitespace color or blue reverse${RESET}" +------------ + +For URLs in `https://weak.example.com`, `http.sslVerify` is set to +false, while it is set to `true` for all others: + +------------ +% git config get --type=bool --url=https://good.example.com http.sslverify +true +% git config get --type=bool --url=https://weak.example.com http.sslverify +false +% git config get --url=https://weak.example.com http +http.cookieFile /tmp/cookie.txt +http.sslverify false +------------ + +include::config.adoc[] + +BUGS +---- +When using the deprecated `[section.subsection]` syntax, changing a value +will result in adding a multi-line key instead of a change, if the subsection +is given with at least one uppercase character. For example when the config +looks like + +-------- + [section.subsection] + key = value1 +-------- + +and running `git config section.Subsection.key value2` will result in + +-------- + [section.subsection] + key = value1 + key = value2 +-------- + + +GIT +--- +Part of the linkgit:git[1] suite |