X-Git-Url: https://git.tokkee.org/?a=blobdiff_plain;f=Documentation%2Fgit-config.txt;h=a592b61e2fe998525d0978547b3ea7e4ad2d72ac;hb=04222b245c5e0d49242ef1ca995fadd5fa082cd3;hp=280ef2058ca95e601243ae57946b80695234c41c;hpb=e986e26a86616054f96373280e8f9cc89d7ea8ca;p=git.git diff --git a/Documentation/git-config.txt b/Documentation/git-config.txt index 280ef2058..a592b61e2 100644 --- a/Documentation/git-config.txt +++ b/Documentation/git-config.txt @@ -9,16 +9,17 @@ git-config - Get and set repository or global options SYNOPSIS -------- [verse] -'git-config' [--system | --global] [type] name [value [value_regex]] -'git-config' [--system | --global] [type] --add name value -'git-config' [--system | --global] [type] --replace-all name [value [value_regex]] -'git-config' [--system | --global] [type] --get name [value_regex] -'git-config' [--system | --global] [type] --get-all name [value_regex] -'git-config' [--system | --global] [type] --unset name [value_regex] -'git-config' [--system | --global] [type] --unset-all name [value_regex] -'git-config' [--system | --global] [type] --rename-section old_name new_name -'git-config' [--system | --global] [type] --remove-section name -'git-config' [--system | --global] -l | --list +'git-config' [] [type] [-z|--null] name [value [value_regex]] +'git-config' [] [type] --add name value +'git-config' [] [type] --replace-all name [value [value_regex]] +'git-config' [] [type] [-z|--null] --get name [value_regex] +'git-config' [] [type] [-z|--null] --get-all name [value_regex] +'git-config' [] [type] [-z|--null] --get-regexp name_regex [value_regex] +'git-config' [] --unset name [value_regex] +'git-config' [] --unset-all name [value_regex] +'git-config' [] --rename-section old_name new_name +'git-config' [] --remove-section name +'git-config' [] [-z|--null] -l | --list DESCRIPTION ----------- @@ -31,23 +32,29 @@ 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 EXAMPLES). +prepend a single exclamation mark in front (see also <>). The type specifier can be either '--int' or '--bool', which will make 'git-config' ensure that the variable(s) are of the given type and convert the value to the canonical form (simple decimal number for int, -a "true" or "false" string for bool). If no type specifier is passed, +a "true" or "false" string for bool). If no type specifier is passed, no checks or transformations are performed on the value. +The file-option can be one of '--system', '--global' or '--file' +which specify where the values will be read from or written to. +The default is to assume the config file of the current repository, +.git/config unless defined otherwise with GIT_DIR and GIT_CONFIG +(see <>). + This command will fail if: -. The .git/config file is invalid, -. Can not write to .git/config, +. The config file is invalid, +. Can not write to the config file, . no section was provided, . the section or key is invalid, . you try to unset an option which does not exist, . you try to unset/set an option for which multiple lines match, or -. you use --global option without $HOME being properly set. +. you use '--global' option without $HOME being properly set. OPTIONS @@ -72,13 +79,28 @@ OPTIONS --get-regexp:: Like --get-all, but interprets the name as a regular expression. + Also outputs the key names. --global:: - Use global ~/.gitconfig file rather than the repository .git/config. + For writing options: write to global ~/.gitconfig file rather than + the repository .git/config. ++ +For reading options: read only from global ~/.gitconfig rather than +from all available files. ++ +See also <>. --system:: - Use system-wide $(prefix)/etc/gitconfig rather than the repository - .git/config. + 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 <>. + +-f config-file, --file config-file:: + Use the given config file instead of the one specified by GIT_CONFIG. --remove-section:: Remove the given section from the configuration file. @@ -104,22 +126,73 @@ OPTIONS in the config file will cause the value to be multiplied by 1024, 1048576, or 1073741824 prior to output. +-z, --null:: + For all options that output values and/or keys, always + end values with 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. + + +[[FILES]] +FILES +----- + +If not set explicitly with '--file', there are three files where +git-config will search for configuration options: + +$GIT_DIR/config:: + Repository specific configuration file. (The filename is + of course relative to the repository root, not the working + directory.) + +~/.gitconfig:: + User-specific configuration file. Also called "global" + configuration file. + +$(prefix)/etc/gitconfig:: + System-wide configuration file. + +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. + +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' and the '--system' options will limit the file used +to the global or system-wide file respectively. The GIT_CONFIG environment +variable has a similar effect, but you can specify any filename you want. + +The GIT_CONFIG_LOCAL environment variable on the other hand only changes +the name used instead of the repository configuration file. The global and +the system-wide configuration files will still be read. (For writing options +this will obviously result in the same behavior as using GIT_CONFIG.) + ENVIRONMENT ----------- GIT_CONFIG:: Take the configuration from the given file instead of .git/config. - Using the "--global" option forces this to ~/.gitconfig. + Using the "--global" option forces this to ~/.gitconfig. Using the + "--system" option forces this to $(prefix)/etc/gitconfig. GIT_CONFIG_LOCAL:: - Currently the same as $GIT_CONFIG; when Git will support global - configuration files, this will cause it to take the configuration - from the global configuration file in addition to the given file. + Take the configuration from the given file instead if .git/config. + Still read the global and the system-wide configuration files, though. +See also <>. -EXAMPLE -------- + +[[EXAMPLES]] +EXAMPLES +-------- Given a .git/config like this: @@ -141,9 +214,7 @@ Given a .git/config like this: ; Proxy settings [core] - gitproxy="ssh" for "ssh://kernel.org/" gitproxy="proxy-command" for kernel.org - gitproxy="myprotocol-command" for "my://" gitproxy=default-proxy ; for all the rest you can set the filemode to true with @@ -218,7 +289,7 @@ To actually match only values with an exclamation mark, you have to To add a new proxy, without altering any of the existing ones, use ------------ -% git config core.gitproxy '"proxy" for example.com' +% git config core.gitproxy '"proxy-command" for example.com' ------------ @@ -236,4 +307,3 @@ Documentation by Johannes Schindelin, Petr Baudis and the git-list