| git-config(1) |
| ============= |
| |
| NAME |
| ---- |
| git-config - Get and set repository or global options |
| |
| |
| SYNOPSIS |
| -------- |
| [verse] |
| 'git config' [<file-option>] [type] [-z|--null] name [value [value_regex]] |
| 'git config' [<file-option>] [type] --add name value |
| '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>] --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>] --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 specifier can be either '--int' or '--bool', to make |
| 'git config' ensure that the variable(s) are of the given type and |
| convert the value to the canonical form (simple decimal number for int, |
| 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. |
| |
| 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>>). |
| |
| 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), 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 error code 2 if multiple key values were found. |
| |
| --get-all:: |
| Like get, but does not fail if the number of values for the key |
| is not exactly one. |
| |
| --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. |
| |
| --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>>. |
| |
| -f config-file:: |
| --file config-file:: |
| Use the given config file instead of the one specified by GIT_CONFIG. |
| |
| --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. |
| |
| --bool:: |
| 'git config' will ensure that the output is "true" or "false" |
| |
| --int:: |
| 'git config' will ensure that the output is a simple |
| decimal number. An optional value suffix of 'k', 'm', or 'g' |
| in the config file will cause the value to be multiplied |
| by 1024, 1048576, or 1073741824 prior to output. |
| |
| --bool-or-int:: |
| 'git config' will ensure that the output matches the format of |
| either --bool or --int, as described above. |
| |
| --path:: |
| 'git-config' will expand leading '{tilde}' to the value of |
| '$HOME', and '{tilde}user' to the home directory for the |
| specified user. This option has no effect when setting the |
| value (but you can use 'git config bla {tilde}/' from the |
| command line to let your shell do the expansion). |
| |
| -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. |
| |
| --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`. |
| |
| -e:: |
| --edit:: |
| Opens an editor to modify the specified config file; either |
| '--system', '--global', or repository (default). |
| |
| --includes:: |
| --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 four files where |
| 'git config' will search for configuration options: |
| |
| $GIT_DIR/config:: |
| Repository specific configuration file. |
| |
| ~/.gitconfig:: |
| User-specific configuration file. Also called "global" |
| 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. |
| |
| $(prefix)/etc/gitconfig:: |
| System-wide 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 |
| 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. |
| |
| 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' 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. |
| |
| |
| 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 |
| |
| 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}" |
| ------------ |
| |
| include::config.txt[] |
| |
| GIT |
| --- |
| Part of the linkgit:git[1] suite |