apply: get rid of --index-info in favor of --build-fake-ancestor
[gitweb.git] / Documentation / git-config.txt
index 280ef2058ca95e601243ae57946b80695234c41c..a592b61e2fe998525d0978547b3ea7e4ad2d72ac 100644 (file)
@@ -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' [<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
 
 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 <<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,
+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 .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 <<FILES>>.
 
 --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 <<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.
@@ -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 <<FILES>>.
 
-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 <git@vger.ker
 GIT
 ---
 Part of the gitlink:git[7] suite
-