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 also <<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         For writing options: write to global ~/.gitconfig file rather than
  79         the repository .git/config.
  80 +
  81 For reading options: read only from global ~/.gitconfig rather than
  82 from all available files.
  83 +
  84 See also <<FILES>>.
  85
  86 --system::
  87         For writing options: write to system-wide $(prefix)/etc/gitconfig
  88         rather than the repository .git/config.
  89 +
  90 For reading options: read only from system-wide $(prefix)/etc/gitconfig
  91 rather than from all available files.
  92 +
  93 See also <<FILES>>.
  94
  95 --remove-section::
  96         Remove the given section from the configuration file.
  97
  98 --rename-section::
  99         Rename the given section to a new name.
 100
 101 --unset::
 102         Remove the line matching the key from config file.
 103
 104 --unset-all::
 105         Remove all lines matching the key from config file.
 106
 107 -l, --list::
 108         List all variables set in config file.
 109
 110 --bool::
 111         git-config will ensure that the output is "true" or "false"
 112
 113 --int::
 114         git-config will ensure that the output is a simple
 115         decimal number.  An optional value suffix of 'k', 'm', or 'g'
 116         in the config file will cause the value to be multiplied
 117         by 1024, 1048576, or 1073741824 prior to output.
 118
 119
 120 [[FILES]]
 121 FILES
 122 -----
 123
 124 There are three files where git-config will search for configuration
 125 options:
 126
 127 .git/config::
 128         Repository specific configuration file. (The filename is
 129         of course relative to the repository root, not the working
 130         directory.)
 131
 132 ~/.gitconfig::
 133         User-specific configuration file. Also called "global"
 134         configuration file.
 135
 136 $(prefix)/etc/gitconfig::
 137         System-wide configuration file.
 138
 139 If no further options are given, all reading options will read all of these
 140 files that are available. If the global or the system-wide configuration
 141 file are not available they will be ignored. If the repository configuration
 142 file is not available or readable, git-config will exit with a non-zero
 143 error code. However, in neither case will an error message be issued.
 144
 145 All writing options will per default write to the repository specific
 146 configuration file. Note that this also affects options like '--replace-all'
 147 and '--unset'. *git-config will only ever change one file at a time*.
 148
 149 You can override these rules either by command line options or by environment
 150 variables. The '--global' and the '--system' options will limit the file used
 151 to the global or system-wide file respectively. The GIT_CONFIG environment
 152 variable has a similar effect, but you can specify any filename you want.
 153
 154 The GIT_CONFIG_LOCAL environment variable on the other hand only changes
 155 the name used instead of the repository configuration file. The global and
 156 the system-wide configuration files will still be read. (For writing options
 157 this will obviously result in the same behavior as using GIT_CONFIG.)
 158
 159
 160 ENVIRONMENT
 161 -----------
 162
 163 GIT_CONFIG::
 164         Take the configuration from the given file instead of .git/config.
 165         Using the "--global" option forces this to ~/.gitconfig. Using the
 166         "--system" option forces this to $(prefix)/etc/gitconfig.
 167
 168 GIT_CONFIG_LOCAL::
 169         Take the configuration from the given file instead if .git/config.
 170         Still read the global and the system-wide configuration files, though.
 171
 172 See also <<FILES>>.
 173
 174
 175 [[EXAMPLES]]
 176 EXAMPLES
 177 --------
 178
 179 Given a .git/config like this:
 180
 181         #
 182         # This is the config file, and
 183         # a '#' or ';' character indicates
 184         # a comment
 185         #
 186
 187         ; core variables
 188         [core]
 189                 ; Don't trust file modes
 190                 filemode = false
 191
 192         ; Our diff algorithm
 193         [diff]
 194                 external = "/usr/local/bin/gnu-diff -u"
 195                 renames = true
 196
 197         ; Proxy settings
 198         [core]
 199                 gitproxy="ssh" for "ssh://kernel.org/"
 200                 gitproxy="proxy-command" for kernel.org
 201                 gitproxy="myprotocol-command" for "my://"
 202                 gitproxy=default-proxy ; for all the rest
 203
 204 you can set the filemode to true with
 205
 206 ------------
 207 % git config core.filemode true
 208 ------------
 209
 210 The hypothetical proxy command entries actually have a postfix to discern
 211 what URL they apply to. Here is how to change the entry for kernel.org
 212 to "ssh".
 213
 214 ------------
 215 % git config core.gitproxy '"ssh" for kernel.org' 'for kernel.org$'
 216 ------------
 217
 218 This makes sure that only the key/value pair for kernel.org is replaced.
 219
 220 To delete the entry for renames, do
 221
 222 ------------
 223 % git config --unset diff.renames
 224 ------------
 225
 226 If you want to delete an entry for a multivar (like core.gitproxy above),
 227 you have to provide a regex matching the value of exactly one line.
 228
 229 To query the value for a given key, do
 230
 231 ------------
 232 % git config --get core.filemode
 233 ------------
 234
 235 or
 236
 237 ------------
 238 % git config core.filemode
 239 ------------
 240
 241 or, to query a multivar:
 242
 243 ------------
 244 % git config --get core.gitproxy "for kernel.org$"
 245 ------------
 246
 247 If you want to know all the values for a multivar, do:
 248
 249 ------------
 250 % git config --get-all core.gitproxy
 251 ------------
 252
 253 If you like to live dangerous, you can replace *all* core.gitproxy by a
 254 new one with
 255
 256 ------------
 257 % git config --replace-all core.gitproxy ssh
 258 ------------
 259
 260 However, if you really only want to replace the line for the default proxy,
 261 i.e. the one without a "for ..." postfix, do something like this:
 262
 263 ------------
 264 % git config core.gitproxy ssh '! for '
 265 ------------
 266
 267 To actually match only values with an exclamation mark, you have to
 268
 269 ------------
 270 % git config section.key value '[!]'
 271 ------------
 272
 273 To add a new proxy, without altering any of the existing ones, use
 274
 275 ------------
 276 % git config core.gitproxy '"proxy" for example.com'
 277 ------------
 278
 279
 280 include::config.txt[]
 281
 282
 283 Author
 284 ------
 285 Written by Johannes Schindelin <Johannes.Schindelin@gmx.de>
 286
 287 Documentation
 288 --------------
 289 Documentation by Johannes Schindelin, Petr Baudis and the git-list <git@vger.kernel.org>.
 290
 291 GIT
 292 ---
 293 Part of the gitlink:git[7] suite