mirror of
https://github.com/git/git
synced 2024-10-30 04:01:21 +00:00
58be11432e
When `--type=<type>` was added as a prefered alias for `--<type>` by
fb0dc3bac1
(builtin/config.c: support `--type=<type>` as preferred
alias for `--<type>`), the explanation for the path type was
reworded. Whereas the previous explanation said "expand a leading
`~`" this was changed to "adding a leading `~`". Change "adding" to
"expanding" to correctly explain the canonicalization.
Signed-off-by: Evan Gates <evan.gates@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
592 lines
19 KiB
Text
592 lines
19 KiB
Text
git-config(1)
|
|
=============
|
|
|
|
NAME
|
|
----
|
|
git-config - Get and set repository or global options
|
|
|
|
|
|
SYNOPSIS
|
|
--------
|
|
[verse]
|
|
'git config' [<file-option>] [--type=<type>] [--fixed-value] [--show-origin] [--show-scope] [-z|--null] <name> [<value> [<value-pattern>]]
|
|
'git config' [<file-option>] [--type=<type>] --add <name> <value>
|
|
'git config' [<file-option>] [--type=<type>] [--fixed-value] --replace-all <name> <value> [<value-pattern>]
|
|
'git config' [<file-option>] [--type=<type>] [--show-origin] [--show-scope] [-z|--null] [--fixed-value] --get <name> [<value-pattern>]
|
|
'git config' [<file-option>] [--type=<type>] [--show-origin] [--show-scope] [-z|--null] [--fixed-value] --get-all <name> [<value-pattern>]
|
|
'git config' [<file-option>] [--type=<type>] [--show-origin] [--show-scope] [-z|--null] [--fixed-value] [--name-only] --get-regexp <name-regex> [<value-pattern>]
|
|
'git config' [<file-option>] [--type=<type>] [-z|--null] --get-urlmatch <name> <URL>
|
|
'git config' [<file-option>] [--fixed-value] --unset <name> [<value-pattern>]
|
|
'git config' [<file-option>] [--fixed-value] --unset-all <name> [<value-pattern>]
|
|
'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 `value-pattern` (which is an extended regular expression,
|
|
unless the `--fixed-value` option is given) needs to be given. Only the
|
|
existing values that match the pattern are updated or unset. If
|
|
you want to handle the lines that do *not* match the pattern, just
|
|
prepend a single exclamation mark in front (see also <<EXAMPLES>>),
|
|
but note that this only works when the `--fixed-value` option is not
|
|
in use.
|
|
|
|
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.
|
|
|
|
A list of all available configuration variables can be obtained using the
|
|
`git help --config` command.
|
|
|
|
[[OPTIONS]]
|
|
OPTIONS
|
|
-------
|
|
|
|
--replace-all::
|
|
Default behavior is to replace at most one line. This replaces
|
|
all lines matching the key (and optionally the `value-pattern`).
|
|
|
|
--add::
|
|
Adds a new line to the option without altering any existing
|
|
values. This is the same as providing '^$' as the `value-pattern`
|
|
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_DIR/config.worktree` is
|
|
read from or written to if `extensions.worktreeConfig` is
|
|
enabled. If not it's the same as `--local`. Note that `$GIT_DIR`
|
|
is equal to `$GIT_COMMON_DIR` for the main working tree, but is of
|
|
the form `$GIT_DIR/worktrees/<id>/` for other working trees. See
|
|
linkgit:git-worktree[1] to learn how to enable
|
|
`extensions.worktreeConfig`.
|
|
|
|
-f <config-file>::
|
|
--file <config-file>::
|
|
For writing options: write to the specified file rather than the
|
|
repository `.git/config`.
|
|
+
|
|
For reading options: read only from the specified file rather than from all
|
|
available files.
|
|
+
|
|
See also <<FILES>>.
|
|
|
|
--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.
|
|
|
|
--fixed-value::
|
|
When used with the `value-pattern` argument, treat `value-pattern` as
|
|
an exact string instead of a regular expression. This will restrict
|
|
the name/value pairs that are matched to only those where the value
|
|
is exactly equal to the `value-pattern`.
|
|
|
|
--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 expanding 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
|
|
(worktree, 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
|
|
-----
|
|
|
|
By default, 'git config' will read configuration options from multiple
|
|
files:
|
|
|
|
$(prefix)/etc/gitconfig::
|
|
System-wide configuration file.
|
|
|
|
$XDG_CONFIG_HOME/git/config::
|
|
~/.gitconfig::
|
|
User-specific configuration files. When the XDG_CONFIG_HOME environment
|
|
variable is not set or empty, $HOME/.config/ is used as
|
|
$XDG_CONFIG_HOME.
|
|
+
|
|
These are also called "global" configuration files. If both files exist, both
|
|
files are read in the order given above.
|
|
|
|
$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.
|
|
|
|
You may also provide additional configuration parameters when running any
|
|
git command by using the `-c` option. See linkgit:git[1] for details.
|
|
|
|
Options will be read from all of these files that are available. If the
|
|
global or the system-wide configuration files are missing or unreadable they
|
|
will be ignored. If the repository configuration file is missing or unreadable,
|
|
'git config' will exit with a non-zero error code. An error message is produced
|
|
if the file is unreadable, but not if it is missing.
|
|
|
|
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.
|
|
|
|
By default, options are only written 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 limit which configuration sources are read from or written to by
|
|
specifying the path of a file with the `--file` option, or by specifying a
|
|
configuration scope with `--system`, `--global`, `--local`, or `--worktree`.
|
|
For more, see <<OPTIONS>> above.
|
|
|
|
[[SCOPES]]
|
|
SCOPES
|
|
------
|
|
|
|
Each configuration source falls within a configuration scope. The scopes
|
|
are:
|
|
|
|
system::
|
|
$(prefix)/etc/gitconfig
|
|
|
|
global::
|
|
$XDG_CONFIG_HOME/git/config
|
|
+
|
|
~/.gitconfig
|
|
|
|
local::
|
|
$GIT_DIR/config
|
|
|
|
worktree::
|
|
$GIT_DIR/config.worktree
|
|
|
|
command::
|
|
GIT_CONFIG_{COUNT,KEY,VALUE} environment variables (see <<ENVIRONMENT>>
|
|
below)
|
|
+
|
|
the `-c` option
|
|
|
|
With the exception of 'command', each scope corresponds to a command line
|
|
option: `--system`, `--global`, `--local`, `--worktree`.
|
|
|
|
When reading options, specifying a scope will only read options from the
|
|
files within that scope. When writing options, specifying a scope will write
|
|
to the files within that scope (instead of the repository specific
|
|
configuration file). See <<OPTIONS>> above for a complete description.
|
|
|
|
Most configuration options are respected regardless of the scope it is
|
|
defined in, but some options are only respected in certain scopes. See the
|
|
respective option's documentation for the full details.
|
|
|
|
Protected configuration
|
|
~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Protected configuration refers to the 'system', 'global', and 'command' scopes.
|
|
For security reasons, certain options are only respected when they are
|
|
specified in protected configuration, and ignored otherwise.
|
|
|
|
Git treats these scopes as if they are controlled by the user or a trusted
|
|
administrator. This is because an attacker who controls these scopes can do
|
|
substantial harm without using Git, so it is assumed that the user's environment
|
|
protects these scopes against attackers.
|
|
|
|
[[ENVIRONMENT]]
|
|
ENVIRONMENT
|
|
-----------
|
|
|
|
GIT_CONFIG_GLOBAL::
|
|
GIT_CONFIG_SYSTEM::
|
|
Take the configuration from the given files instead from global or
|
|
system-level configuration. See linkgit:git[1] for details.
|
|
|
|
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>>.
|
|
|
|
GIT_CONFIG_COUNT::
|
|
GIT_CONFIG_KEY_<n>::
|
|
GIT_CONFIG_VALUE_<n>::
|
|
If GIT_CONFIG_COUNT is set to a positive number, all environment pairs
|
|
GIT_CONFIG_KEY_<n> and GIT_CONFIG_VALUE_<n> up to that number will be
|
|
added to the process's runtime configuration. The config pairs are
|
|
zero-indexed. Any missing key or value is treated as an error. An empty
|
|
GIT_CONFIG_COUNT is treated the same as GIT_CONFIG_COUNT=0, namely no
|
|
pairs are processed. These environment variables will override values
|
|
in configuration files, but will be overridden by any explicit options
|
|
passed via `git -c`.
|
|
+
|
|
This is useful for cases where you want to spawn multiple git commands
|
|
with a common configuration but cannot depend on a configuration file,
|
|
for example when writing scripts.
|
|
|
|
GIT_CONFIG::
|
|
If no `--file` option is provided to `git config`, use the file
|
|
given by `GIT_CONFIG` as if it were provided via `--file`. This
|
|
variable has no effect on other Git commands, and is mostly for
|
|
historical compatibility; there is generally no reason to use it
|
|
instead of the `--file` option.
|
|
|
|
[[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
|