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.
500 lines
16 KiB
500 lines
16 KiB
git-config(1) |
|
============= |
|
|
|
NAME |
|
---- |
|
git-config - Get and set repository or global options |
|
|
|
|
|
SYNOPSIS |
|
-------- |
|
[verse] |
|
'git config' [<file-option>] [--type=<type>] [--show-origin] [--show-scope] [-z|--null] name [value [value_regex]] |
|
'git config' [<file-option>] [--type=<type>] --add name value |
|
'git config' [<file-option>] [--type=<type>] --replace-all name value [value_regex] |
|
'git config' [<file-option>] [--type=<type>] [--show-origin] [--show-scope] [-z|--null] --get name [value_regex] |
|
'git config' [<file-option>] [--type=<type>] [--show-origin] [--show-scope] [-z|--null] --get-all name [value_regex] |
|
'git config' [<file-option>] [--type=<type>] [--show-origin] [--show-scope] [-z|--null] [--name-only] --get-regexp name_regex [value_regex] |
|
'git config' [<file-option>] [--type=<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>] [--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 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=<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. |
|
|
|
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 |
|
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/config.worktree` is |
|
read from or written to if `extensions.worktreeConfig` is |
|
present. If not it's the same as `--local`. |
|
|
|
-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. |
|
|
|
--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. |
|
|
|
--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 |
|
(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 |
|
----- |
|
|
|
If not set explicitly with `--file`, there are four files where |
|
'git config' will search for configuration options: |
|
|
|
$(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. |
|
|
|
$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. |
|
|
|
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. |
|
|
|
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. |
|
|
|
You may override individual configuration parameters when running any git |
|
command by using the `-c` option. See linkgit:git[1] for details. |
|
|
|
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`, `--system` and `--worktree` options will limit |
|
the file used to the global, system-wide or per-worktree file respectively. |
|
The `GIT_CONFIG` environment variable has a similar effect, but you |
|
can specify any filename you want. |
|
|
|
|
|
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_NOSYSTEM:: |
|
Whether to skip reading settings from the system-wide |
|
$(prefix)/etc/gitconfig file. See linkgit:git[1] for details. |
|
|
|
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/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
|
|
|