Documentation/git-config.txt

   1 git-config(1)
   2 =============
   3
   4 NAME
   5 ----
   6 git-config - Get and set repository or global options
   7
   8
   9 SYNOPSIS
  10 --------
  11 [verse]
  12 'git-config' [--system | --global] name [value [value_regex]]
  13 'git-config' [--system | --global] --add name value
  14 'git-config' [--system | --global] --replace-all name [value [value_regex]]
  15 'git-config' [--system | --global] [type] --get name [value_regex]
  16 'git-config' [--system | --global] [type] --get-all name [value_regex]
  17 'git-config' [--system | --global] --unset name [value_regex]
  18 'git-config' [--system | --global] --unset-all name [value_regex]
  19 'git-config' [--system | --global] --rename-section old_name new_name
  20 'git-config' [--system | --global] --remove-section name
  21 'git-config' [--system | --global] -l | --list
  22
  23 DESCRIPTION
  24 -----------
  25 You can query/set/replace/unset options with this command. The name is
  26 actually the section and the key separated by a dot, and the value will be
  27 escaped.
  28
  29 Multiple lines can be added to an option by using the '--add' option.
  30 If you want to update or unset an option which can occur on multiple
  31 lines, a POSIX regexp `value_regex` needs to be given.  Only the
  32 existing values that match the regexp are updated or unset.  If
  33 you want to handle the lines that do *not* match the regex, just
  34 prepend a single exclamation mark in front (see EXAMPLES).
  35
  36 The type specifier can be either '--int' or '--bool', which will make
  37 'git-config' ensure that the variable(s) are of the given type and
  38 convert the value to the canonical form (simple decimal number for int,
  39 a "true" or "false" string for bool).  Type specifiers currently only
  40 take effect for reading operations.  If no type specifier is passed,
  41 no checks or transformations are performed on the value.
  42
  43 This command will fail if:
  44
  45 . The .git/config file is invalid,
  46 . Can not write to .git/config,
  47 . no section was provided,
  48 . the section or key is invalid,
  49 . you try to unset an option which does not exist,
  50 . you try to unset/set an option for which multiple lines match, or
  51 . you use --global option without $HOME being properly set.
  52
  53
  54 OPTIONS
  55 -------
  56
  57 --replace-all::
  58         Default behavior is to replace at most one line. This replaces
  59         all lines matching the key (and optionally the value_regex).
  60
  61 --add::
  62         Adds a new line to the option without altering any existing
  63         values.  This is the same as providing '^$' as the value_regex.
  64
  65 --get::
  66         Get the value for a given key (optionally filtered by a regex
  67         matching the value). Returns error code 1 if the key was not
  68         found and error code 2 if multiple key values were found.
  69
  70 --get-all::
  71         Like get, but does not fail if the number of values for the key
  72         is not exactly one.
  73
  74 --get-regexp::
  75         Like --get-all, but interprets the name as a regular expression.
  76
  77 --global::
  78         Use global ~/.gitconfig file rather than the repository .git/config.
  79
  80 --system::
  81         Use system-wide $(prefix)/etc/gitconfig rather than the repository
  82         .git/config.
  83
  84 --remove-section::
  85         Remove the given section from the configuration file.
  86
  87 --rename-section::
  88         Rename the given section to a new name.
  89
  90 --unset::
  91         Remove the line matching the key from config file.
  92
  93 --unset-all::
  94         Remove all lines matching the key from config file.
  95
  96 -l, --list::
  97         List all variables set in config file.
  98
  99 --bool::
 100         git-config will ensure that the output is "true" or "false"
 101
 102 --int::
 103         git-config will ensure that the output is a simple
 104         decimal number.  An optional value suffix of 'k', 'm', or 'g'
 105         in the config file will cause the value to be multiplied
 106         by 1024, 1048576, or 1073741824 prior to output.
 107
 108
 109 ENVIRONMENT
 110 -----------
 111
 112 GIT_CONFIG::
 113         Take the configuration from the given file instead of .git/config.
 114         Using the "--global" option forces this to ~/.gitconfig.
 115
 116 GIT_CONFIG_LOCAL::
 117         Currently the same as $GIT_CONFIG; when Git will support global
 118         configuration files, this will cause it to take the configuration
 119         from the global configuration file in addition to the given file.
 120
 121
 122 EXAMPLE
 123 -------
 124
 125 Given a .git/config like this:
 126
 127         #
 128         # This is the config file, and
 129         # a '#' or ';' character indicates
 130         # a comment
 131         #
 132
 133         ; core variables
 134         [core]
 135                 ; Don't trust file modes
 136                 filemode = false
 137
 138         ; Our diff algorithm
 139         [diff]
 140                 external = "/usr/local/bin/gnu-diff -u"
 141                 renames = true
 142
 143         ; Proxy settings
 144         [core]
 145                 gitproxy="ssh" for "ssh://kernel.org/"
 146                 gitproxy="proxy-command" for kernel.org
 147                 gitproxy="myprotocol-command" for "my://"
 148                 gitproxy=default-proxy ; for all the rest
 149
 150 you can set the filemode to true with
 151
 152 ------------
 153 % git config core.filemode true
 154 ------------
 155
 156 The hypothetical proxy command entries actually have a postfix to discern
 157 what URL they apply to. Here is how to change the entry for kernel.org
 158 to "ssh".
 159
 160 ------------
 161 % git config core.gitproxy '"ssh" for kernel.org' 'for kernel.org$'
 162 ------------
 163
 164 This makes sure that only the key/value pair for kernel.org is replaced.
 165
 166 To delete the entry for renames, do
 167
 168 ------------
 169 % git config --unset diff.renames
 170 ------------
 171
 172 If you want to delete an entry for a multivar (like core.gitproxy above),
 173 you have to provide a regex matching the value of exactly one line.
 174
 175 To query the value for a given key, do
 176
 177 ------------
 178 % git config --get core.filemode
 179 ------------
 180
 181 or
 182
 183 ------------
 184 % git config core.filemode
 185 ------------
 186
 187 or, to query a multivar:
 188
 189 ------------
 190 % git config --get core.gitproxy "for kernel.org$"
 191 ------------
 192
 193 If you want to know all the values for a multivar, do:
 194
 195 ------------
 196 % git config --get-all core.gitproxy
 197 ------------
 198
 199 If you like to live dangerous, you can replace *all* core.gitproxy by a
 200 new one with
 201
 202 ------------
 203 % git config --replace-all core.gitproxy ssh
 204 ------------
 205
 206 However, if you really only want to replace the line for the default proxy,
 207 i.e. the one without a "for ..." postfix, do something like this:
 208
 209 ------------
 210 % git config core.gitproxy ssh '! for '
 211 ------------
 212
 213 To actually match only values with an exclamation mark, you have to
 214
 215 ------------
 216 % git config section.key value '[!]'
 217 ------------
 218
 219 To add a new proxy, without altering any of the existing ones, use
 220
 221 ------------
 222 % git config core.gitproxy '"proxy" for example.com'
 223 ------------
 224
 225
 226 include::config.txt[]
 227
 228
 229 Author
 230 ------
 231 Written by Johannes Schindelin <Johannes.Schindelin@gmx.de>
 232
 233 Documentation
 234 --------------
 235 Documentation by Johannes Schindelin, Petr Baudis and the git-list <git@vger.kernel.org>.
 236
 237 GIT
 238 ---
 239 Part of the gitlink:git[7] suite
 240