diff options
Diffstat (limited to 'Documentation/git-config.txt')
| -rw-r--r-- | Documentation/git-config.txt | 500 |
1 files changed, 500 insertions, 0 deletions
diff --git a/Documentation/git-config.txt b/Documentation/git-config.txt new file mode 100644 index 0000000000..7573160f21 --- /dev/null +++ b/Documentation/git-config.txt @@ -0,0 +1,500 @@ +git-config(1) +============= + +NAME +---- +git-config - Get and set repository or global options + + +SYNOPSIS +-------- +[verse] +'git config' [<file-option>] [--type=<type>] [--show-origin] [--show-scope] [-z|--null] name [value [value_regex]] +'git config' [<file-option>] [--type=<type>] --add name value +'git config' [<file-option>] [--type=<type>] --replace-all name value [value_regex] +'git config' [<file-option>] [--type=<type>] [--show-origin] [--show-scope] [-z|--null] --get name [value_regex] +'git config' [<file-option>] [--type=<type>] [--show-origin] [--show-scope] [-z|--null] --get-all name [value_regex] +'git config' [<file-option>] [--type=<type>] [--show-origin] [--show-scope] [-z|--null] [--name-only] --get-regexp name_regex [value_regex] +'git config' [<file-option>] [--type=<type>] [-z|--null] --get-urlmatch name URL +'git config' [<file-option>] --unset name [value_regex] +'git config' [<file-option>] --unset-all name [value_regex] +'git config' [<file-option>] --rename-section old_name new_name +'git config' [<file-option>] --remove-section name +'git config' [<file-option>] [--show-origin] [--show-scope] [-z|--null] [--name-only] -l | --list +'git config' [<file-option>] --get-color name [default] +'git config' [<file-option>] --get-colorbool name [stdout-is-tty] +'git config' [<file-option>] -e | --edit + +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 `--add` option. +If you want to update or unset an option which can occur on multiple +lines, a POSIX regexp `value_regex` needs to be given. Only the +existing values that match the regexp are updated or unset. If +you want to handle the lines that do *not* match the regex, just +prepend a single exclamation mark in front (see also <<EXAMPLES>>). + +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. + +OPTIONS +------- + +--replace-all:: + Default behavior is to replace at most one line. This replaces + all lines matching the key (and optionally the value_regex). + +--add:: + Adds a new line to the option without altering any existing + values. This is the same as providing '^$' as the value_regex + in `--replace-all`. + +--get:: + Get the value for a given key (optionally filtered by a regex + matching the value). Returns error code 1 if the key was not + found and the last value if multiple key values were found. + +--get-all:: + Like get, but returns all values for a multi-valued key. + +--get-regexp:: + Like --get-all, but interprets the name as a regular expression and + writes out the key names. 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. + +--get-urlmatch name URL:: + When given a two-part name 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/config.worktree` is + read from or written to if `extensions.worktreeConfig` is + present. If not it's the same as `--local`. + +-f config-file:: +--file config-file:: + Use the given config file instead of the one specified by GIT_CONFIG. + +--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. + +--remove-section:: + Remove the given section from the configuration file. + +--rename-section:: + Rename the given section to a new name. + +--unset:: + Remove the line matching the key from config file. + +--unset-all:: + Remove all lines matching the key from config file. + +-l:: +--list:: + List all variables set in config file, along with their values. + +--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 as either "true" or "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 adding 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-regexp`. + +--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 + (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. + +--get-color name [default]:: + + Find the color configured for `name` (e.g. `color.diff.new`) and + output it as the ANSI color escape sequence to the standard + output. The optional `default` parameter is used instead, if + there is no color configured for `name`. ++ +`--type=color [--default=<default>]` is preferred over `--get-color` +(but note that `--get-color` will omit the trailing newline printed by +`--type=color`). + +-e:: +--edit:: + Opens an editor to modify the specified config file; either + `--system`, `--global`, or repository (default). + +--[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 the that variable. + +CONFIGURATION +------------- +`pager.config` is only respected when listing configuration, i.e., when +using `--list` or any of the `--get-*` which may return multiple results. +The default is to use a pager. + +[[FILES]] +FILES +----- + +If not set explicitly with `--file`, there are four files where +'git config' will search for configuration options: + +$(prefix)/etc/gitconfig:: + System-wide configuration file. + +$XDG_CONFIG_HOME/git/config:: + Second user-specific configuration file. If $XDG_CONFIG_HOME is not set + or empty, `$HOME/.config/git/config` will be used. Any single-valued + variable set in this file will be overwritten by whatever is in + `~/.gitconfig`. It is a good idea not to create this file if + you sometimes use older versions of Git, as support for this + file was added fairly recently. + +~/.gitconfig:: + User-specific configuration file. Also called "global" + configuration file. + +$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. + +If no further options are given, all reading options will read all of these +files that are available. If the global or the system-wide configuration +file are not available they will be ignored. If the repository configuration +file is not available or readable, 'git config' will exit with a non-zero +error code. However, in neither case will an error message be issued. + +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. + +You may override individual configuration parameters when running any git +command by using the `-c` option. See linkgit:git[1] for details. + +All writing options will per default write to the repository specific +configuration file. Note that this also affects options like `--replace-all` +and `--unset`. *'git config' will only ever change one file at a time*. + +You can override these rules either by command-line options or by environment +variables. The `--global`, `--system` and `--worktree` options will limit +the file used to the global, system-wide or per-worktree file respectively. +The `GIT_CONFIG` environment variable has a similar effect, but you +can specify any filename you want. + + +ENVIRONMENT +----------- + +GIT_CONFIG:: + Take the configuration from the given file instead of .git/config. + Using the "--global" option forces this to ~/.gitconfig. Using the + "--system" option forces this to $(prefix)/etc/gitconfig. + +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>>. + + +[[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 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 core.gitproxy '"ssh" for kernel.org' '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 + +------------ +% git config core.filemode +------------ + +or, to query a multivar: + +------------ +% git config --get core.gitproxy "for kernel.org$" +------------ + +If you want to know all the values for a multivar, do: + +------------ +% git config --get-all core.gitproxy +------------ + +If you like to live dangerously, you can replace *all* core.gitproxy by a +new one with + +------------ +% git config --replace-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 core.gitproxy ssh '! for ' +------------ + +To actually match only values with an exclamation mark, you have to + +------------ +% git config section.key value '[!]' +------------ + +To add a new proxy, without altering any of the existing ones, use + +------------ +% git config --add 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-color color.diff.whitespace "blue reverse") +RESET=$(git config --get-color "" "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 --type=bool --get-urlmatch http.sslverify https://good.example.com +true +% git config --type=bool --get-urlmatch http.sslverify https://weak.example.com +false +% git config --get-urlmatch http https://weak.example.com +http.cookieFile /tmp/cookie.txt +http.sslverify false +------------ + +include::config.txt[] + +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 |