You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
592 lines
19 KiB
592 lines
19 KiB
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 adding 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
|
|
|