| 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 |