summaryrefslogtreecommitdiff
path: root/Documentation/git-config.txt
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/git-config.txt')
-rw-r--r--Documentation/git-config.txt134
1 files changed, 104 insertions, 30 deletions
diff --git a/Documentation/git-config.txt b/Documentation/git-config.txt
index 7617d9eb24..2608ca74ac 100644
--- a/Documentation/git-config.txt
+++ b/Documentation/git-config.txt
@@ -14,12 +14,13 @@ SYNOPSIS
'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>] [type] [-z|--null] [--name-only] --get-regexp name_regex [value_regex]
+'git config' [<file-option>] [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>] [-z|--null] -l | --list
+'git config' [<file-option>] [-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
@@ -44,22 +45,26 @@ a "true" or "false" string for bool), or '--path', which does some
path expansion (see '--path' below). 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>>).
+When reading, the values are read from the system, global and
+repository local configuration files by default, and options
+'--system', '--global', '--local' and '--file <filename>' can be
+used to tell the command to read from only that location (see <<FILES>>).
-This command will fail (with exit code ret) if:
+When writing, the new value is written to the repository local
+configuration file by default, and options '--system', '--global',
+'--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 config file is invalid (ret=3),
. can not write to the config file (ret=4),
. no section or name was provided (ret=2),
. the section or key is invalid (ret=1),
. 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),
-. you try to use an invalid regexp (ret=6), or
-. you use '--global' option without $HOME being properly set (ret=128).
+. 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.
@@ -78,7 +83,7 @@ OPTIONS
--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.
+ found and the last value if multiple key values were found.
--get-all::
Like get, but does not fail if the number of values for the key
@@ -91,28 +96,55 @@ OPTIONS
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.
+
--global::
- For writing options: write to global ~/.gitconfig file rather than
- the repository .git/config.
+ 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 rather than
-from all available files.
+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 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
+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>>.
+
-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.
@@ -127,7 +159,7 @@ See also <<FILES>>.
-l::
--list::
- List all variables set in config file.
+ List all variables set in config file, along with their values.
--bool::
'git config' will ensure that the output is "true" or "false"
@@ -158,6 +190,10 @@ See also <<FILES>>.
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`.
+
--get-colorbool name [stdout-is-tty]::
Find the color setting for `name` (e.g. `color.diff`) and output
@@ -181,24 +217,34 @@ See also <<FILES>>.
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 on.
+
[[FILES]]
FILES
-----
-If not set explicitly with '--file', there are three files where
+If not set explicitly with '--file', there are four 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.)
+$(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.
-$(prefix)/etc/gitconfig::
- System-wide configuration file.
+$GIT_DIR/config::
+ Repository specific 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
@@ -206,11 +252,15 @@ 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.
+
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
+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.
@@ -224,6 +274,10 @@ 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>>.
@@ -251,9 +305,16 @@ Given a .git/config like this:
; Proxy settings
[core]
- gitproxy="proxy-command" for kernel.org
+ 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
------------
@@ -326,7 +387,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-command" for example.com'
+% git config --add core.gitproxy '"proxy-command" for example.com'
------------
An example to use customized color from the configuration in your
@@ -339,6 +400,19 @@ 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 --bool --get-urlmatch http.sslverify https://good.example.com
+true
+% git config --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[]
GIT