diff options
Diffstat (limited to 'Documentation/git-config.txt')
| -rw-r--r-- | Documentation/git-config.txt | 335 |
1 files changed, 335 insertions, 0 deletions
diff --git a/Documentation/git-config.txt b/Documentation/git-config.txt new file mode 100644 index 0000000000..fa161718dd --- /dev/null +++ b/Documentation/git-config.txt @@ -0,0 +1,335 @@ +git-config(1) +============= + +NAME +---- +git-config - Get and set repository or global options + + +SYNOPSIS +-------- +[verse] +'git-config' [<file-option>] [type] [-z|--null] name [value [value_regex]] +'git-config' [<file-option>] [type] --add name value +'git-config' [<file-option>] [type] --replace-all name [value [value_regex]] +'git-config' [<file-option>] [type] [-z|--null] --get name [value_regex] +'git-config' [<file-option>] [type] [-z|--null] --get-all name [value_regex] +'git-config' [<file-option>] [type] [-z|--null] --get-regexp name_regex [value_regex] +'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>] [-z|--null] -l | --list +'git-config' [<file-option>] --get-color name [default] +'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 '--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 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, +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 <<FILES>>). + +This command will fail if: + +. 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. + + +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. + +--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 error code 2 if multiple key values were found. + +--get-all:: + Like get, but does not fail if the number of values for the key + is not exactly one. + +--get-regexp:: + Like --get-all, but interprets the name as a regular expression. + Also outputs the key names. + +--global:: + 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 <<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>>. + +-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. + +--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. + +--bool:: + git-config will ensure that the output is "true" or "false" + +--int:: + git-config will ensure that the output is a simple + decimal number. An optional value suffix of 'k', 'm', or 'g' + 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 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. + +--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. + +--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`. + +[[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 + "--system" option forces this to $(prefix)/etc/gitconfig. + +GIT_CONFIG_LOCAL:: + Take the configuration from the given file instead if .git/config. + Still read the global and the system-wide configuration files, though. + +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/gnu-diff -u" + renames = true + + ; Proxy settings + [core] + gitproxy="proxy-command" for kernel.org + gitproxy=default-proxy ; for all the rest + +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 dangerous, 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 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}" +------------ + +include::config.txt[] + + +Author +------ +Written by Johannes Schindelin <Johannes.Schindelin@gmx.de> + +Documentation +-------------- +Documentation by Johannes Schindelin, Petr Baudis and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the linkgit:git[7] suite |