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' [<file-option>] [--type=<type>] [--fixed-value] [--show-origin] [--show-scope] [-z|--null] <name> [<value> [<value-pattern>]]
  13 'git config' [<file-option>] [--type=<type>] --add <name> <value>
  14 'git config' [<file-option>] [--type=<type>] [--fixed-value] --replace-all <name> <value> [<value-pattern>]
  15 'git config' [<file-option>] [--type=<type>] [--show-origin] [--show-scope] [-z|--null] [--fixed-value] --get <name> [<value-pattern>]
  16 'git config' [<file-option>] [--type=<type>] [--show-origin] [--show-scope] [-z|--null] [--fixed-value] --get-all <name> [<value-pattern>]
  17 'git config' [<file-option>] [--type=<type>] [--show-origin] [--show-scope] [-z|--null] [--fixed-value] [--name-only] --get-regexp <name-regex> [<value-pattern>]
  18 'git config' [<file-option>] [--type=<type>] [-z|--null] --get-urlmatch <name> <URL>
  19 'git config' [<file-option>] [--fixed-value] --unset <name> [<value-pattern>]
  20 'git config' [<file-option>] [--fixed-value] --unset-all <name> [<value-pattern>]
  21 'git config' [<file-option>] --rename-section <old-name> <new-name>
  22 'git config' [<file-option>] --remove-section <name>
  23 'git config' [<file-option>] [--show-origin] [--show-scope] [-z|--null] [--name-only] -l | --list
  24 'git config' [<file-option>] --get-color <name> [<default>]
  25 'git config' [<file-option>] --get-colorbool <name> [<stdout-is-tty>]
  26 'git config' [<file-option>] -e | --edit
  27
  28 DESCRIPTION
  29 -----------
  30 You can query/set/replace/unset options with this command. The name is
  31 actually the section and the key separated by a dot, and the value will be
  32 escaped.
  33
  34 Multiple lines can be added to an option by using the `--add` option.
  35 If you want to update or unset an option which can occur on multiple
  36 lines, a `value-pattern` (which is an extended regular expression,
  37 unless the `--fixed-value` option is given) needs to be given.  Only the
  38 existing values that match the pattern are updated or unset.  If
  39 you want to handle the lines that do *not* match the pattern, just
  40 prepend a single exclamation mark in front (see also <<EXAMPLES>>),
  41 but note that this only works when the `--fixed-value` option is not
  42 in use.
  43
  44 The `--type=<type>` option instructs 'git config' to ensure that incoming and
  45 outgoing values are canonicalize-able under the given <type>.  If no
  46 `--type=<type>` is given, no canonicalization will be performed. Callers may
  47 unset an existing `--type` specifier with `--no-type`.
  48
  49 When reading, the values are read from the system, global and
  50 repository local configuration files by default, and options
  51 `--system`, `--global`, `--local`, `--worktree` and
  52 `--file <filename>` can be used to tell the command to read from only
  53 that location (see <<FILES>>).
  54
  55 When writing, the new value is written to the repository local
  56 configuration file by default, and options `--system`, `--global`,
  57 `--worktree`, `--file <filename>` can be used to tell the command to
  58 write to that location (you can say `--local` but that is the
  59 default).
  60
  61 This command will fail with non-zero status upon error.  Some exit
  62 codes are:
  63
  64 - The section or key is invalid (ret=1),
  65 - no section or name was provided (ret=2),
  66 - the config file is invalid (ret=3),
  67 - the config file cannot be written (ret=4),
  68 - you try to unset an option which does not exist (ret=5),
  69 - you try to unset/set an option for which multiple lines match (ret=5), or
  70 - you try to use an invalid regexp (ret=6).
  71
  72 On success, the command returns the exit code 0.
  73
  74 A list of all available configuration variables can be obtained using the
  75 `git help --config` command.
  76
  77 [[OPTIONS]]
  78 OPTIONS
  79 -------
  80
  81 --replace-all::
  82         Default behavior is to replace at most one line. This replaces
  83         all lines matching the key (and optionally the `value-pattern`).
  84
  85 --add::
  86         Adds a new line to the option without altering any existing
  87         values.  This is the same as providing '^$' as the `value-pattern`
  88         in `--replace-all`.
  89
  90 --get::
  91         Get the value for a given key (optionally filtered by a regex
  92         matching the value). Returns error code 1 if the key was not
  93         found and the last value if multiple key values were found.
  94
  95 --get-all::
  96         Like get, but returns all values for a multi-valued key.
  97
  98 --get-regexp::
  99         Like --get-all, but interprets the name as a regular expression and
 100         writes out the key names.  Regular expression matching is currently
 101         case-sensitive and done against a canonicalized version of the key
 102         in which section and variable names are lowercased, but subsection
 103         names are not.
 104
 105 --get-urlmatch <name> <URL>::
 106         When given a two-part name section.key, the value for
 107         section.<URL>.key whose <URL> part matches the best to the
 108         given URL is returned (if no such key exists, the value for
 109         section.key is used as a fallback).  When given just the
 110         section as name, do so for all the keys in the section and
 111         list them.  Returns error code 1 if no value is found.
 112
 113 --global::
 114         For writing options: write to global `~/.gitconfig` file
 115         rather than the repository `.git/config`, write to
 116         `$XDG_CONFIG_HOME/git/config` file if this file exists and the
 117         `~/.gitconfig` file doesn't.
 118 +
 119 For reading options: read only from global `~/.gitconfig` and from
 120 `$XDG_CONFIG_HOME/git/config` rather than from all available files.
 121 +
 122 See also <<FILES>>.
 123
 124 --system::
 125         For writing options: write to system-wide
 126         `$(prefix)/etc/gitconfig` rather than the repository
 127         `.git/config`.
 128 +
 129 For reading options: read only from system-wide `$(prefix)/etc/gitconfig`
 130 rather than from all available files.
 131 +
 132 See also <<FILES>>.
 133
 134 --local::
 135         For writing options: write to the repository `.git/config` file.
 136         This is the default behavior.
 137 +
 138 For reading options: read only from the repository `.git/config` rather than
 139 from all available files.
 140 +
 141 See also <<FILES>>.
 142
 143 --worktree::
 144         Similar to `--local` except that `.git/config.worktree` is
 145         read from or written to if `extensions.worktreeConfig` is
 146         present. If not it's the same as `--local`.
 147
 148 -f <config-file>::
 149 --file <config-file>::
 150         For writing options: write to the specified file rather than the
 151         repository `.git/config`.
 152 +
 153 For reading options: read only from the specified file rather than from all
 154 available files.
 155 +
 156 See also <<FILES>>.
 157
 158 --blob <blob>::
 159         Similar to `--file` but use the given blob instead of a file. E.g.
 160         you can use 'master:.gitmodules' to read values from the file
 161         '.gitmodules' in the master branch. See "SPECIFYING REVISIONS"
 162         section in linkgit:gitrevisions[7] for a more complete list of
 163         ways to spell blob names.
 164
 165 --remove-section::
 166         Remove the given section from the configuration file.
 167
 168 --rename-section::
 169         Rename the given section to a new name.
 170
 171 --unset::
 172         Remove the line matching the key from config file.
 173
 174 --unset-all::
 175         Remove all lines matching the key from config file.
 176
 177 -l::
 178 --list::
 179         List all variables set in config file, along with their values.
 180
 181 --fixed-value::
 182         When used with the `value-pattern` argument, treat `value-pattern` as
 183         an exact string instead of a regular expression. This will restrict
 184         the name/value pairs that are matched to only those where the value
 185         is exactly equal to the `value-pattern`.
 186
 187 --type <type>::
 188   'git config' will ensure that any input or output is valid under the given
 189   type constraint(s), and will canonicalize outgoing values in `<type>`'s
 190   canonical form.
 191 +
 192 Valid `<type>`'s include:
 193 +
 194 - 'bool': canonicalize values as either "true" or "false".
 195 - 'int': canonicalize values as simple decimal numbers. An optional suffix of
 196   'k', 'm', or 'g' will cause the value to be multiplied by 1024, 1048576, or
 197   1073741824 upon input.
 198 - 'bool-or-int': canonicalize according to either 'bool' or 'int', as described
 199   above.
 200 - 'path': canonicalize by adding a leading `~` to the value of `$HOME` and
 201   `~user` to the home directory for the specified user. This specifier has no
 202   effect when setting the value (but you can use `git config section.variable
 203   ~/` from the command line to let your shell do the expansion.)
 204 - 'expiry-date': canonicalize by converting from a fixed or relative date-string
 205   to a timestamp. This specifier has no effect when setting the value.
 206 - 'color': When getting a value, canonicalize by converting to an ANSI color
 207   escape sequence. When setting a value, a sanity-check is performed to ensure
 208   that the given value is canonicalize-able as an ANSI color, but it is written
 209   as-is.
 210 +
 211
 212 --bool::
 213 --int::
 214 --bool-or-int::
 215 --path::
 216 --expiry-date::
 217   Historical options for selecting a type specifier. Prefer instead `--type`
 218   (see above).
 219
 220 --no-type::
 221   Un-sets the previously set type specifier (if one was previously set). This
 222   option requests that 'git config' not canonicalize the retrieved variable.
 223   `--no-type` has no effect without `--type=<type>` or `--<type>`.
 224
 225 -z::
 226 --null::
 227         For all options that output values and/or keys, always
 228         end values with the null character (instead of a
 229         newline). Use newline instead as a delimiter between
 230         key and value. This allows for secure parsing of the
 231         output without getting confused e.g. by values that
 232         contain line breaks.
 233
 234 --name-only::
 235         Output only the names of config variables for `--list` or
 236         `--get-regexp`.
 237
 238 --show-origin::
 239         Augment the output of all queried config options with the
 240         origin type (file, standard input, blob, command line) and
 241         the actual origin (config file path, ref, or blob id if
 242         applicable).
 243
 244 --show-scope::
 245         Similar to `--show-origin` in that it augments the output of
 246         all queried config options with the scope of that value
 247         (local, global, system, command).
 248
 249 --get-colorbool <name> [<stdout-is-tty>]::
 250
 251         Find the color setting for `<name>` (e.g. `color.diff`) and output
 252         "true" or "false".  `<stdout-is-tty>` should be either "true" or
 253         "false", and is taken into account when configuration says
 254         "auto".  If `<stdout-is-tty>` is missing, then checks the standard
 255         output of the command itself, and exits with status 0 if color
 256         is to be used, or exits with status 1 otherwise.
 257         When the color setting for `name` is undefined, the command uses
 258         `color.ui` as fallback.
 259
 260 --get-color <name> [<default>]::
 261
 262         Find the color configured for `name` (e.g. `color.diff.new`) and
 263         output it as the ANSI color escape sequence to the standard
 264         output.  The optional `default` parameter is used instead, if
 265         there is no color configured for `name`.
 266 +
 267 `--type=color [--default=<default>]` is preferred over `--get-color`
 268 (but note that `--get-color` will omit the trailing newline printed by
 269 `--type=color`).
 270
 271 -e::
 272 --edit::
 273         Opens an editor to modify the specified config file; either
 274         `--system`, `--global`, or repository (default).
 275
 276 --[no-]includes::
 277         Respect `include.*` directives in config files when looking up
 278         values. Defaults to `off` when a specific file is given (e.g.,
 279         using `--file`, `--global`, etc) and `on` when searching all
 280         config files.
 281
 282 --default <value>::
 283   When using `--get`, and the requested variable is not found, behave as if
 284   <value> were the value assigned to the that variable.
 285
 286 CONFIGURATION
 287 -------------
 288 `pager.config` is only respected when listing configuration, i.e., when
 289 using `--list` or any of the `--get-*` which may return multiple results.
 290 The default is to use a pager.
 291
 292 [[FILES]]
 293 FILES
 294 -----
 295
 296 If not set explicitly with `--file`, there are four files where
 297 'git config' will search for configuration options:
 298
 299 $(prefix)/etc/gitconfig::
 300         System-wide configuration file.
 301
 302 $XDG_CONFIG_HOME/git/config::
 303         Second user-specific configuration file. If $XDG_CONFIG_HOME is not set
 304         or empty, `$HOME/.config/git/config` will be used. Any single-valued
 305         variable set in this file will be overwritten by whatever is in
 306         `~/.gitconfig`.  It is a good idea not to create this file if
 307         you sometimes use older versions of Git, as support for this
 308         file was added fairly recently.
 309
 310 ~/.gitconfig::
 311         User-specific configuration file. Also called "global"
 312         configuration file.
 313
 314 $GIT_DIR/config::
 315         Repository specific configuration file.
 316
 317 $GIT_DIR/config.worktree::
 318         This is optional and is only searched when
 319         `extensions.worktreeConfig` is present in $GIT_DIR/config.
 320
 321 If no further options are given, all reading options will read all of these
 322 files that are available. If the global or the system-wide configuration
 323 file are not available they will be ignored. If the repository configuration
 324 file is not available or readable, 'git config' will exit with a non-zero
 325 error code. However, in neither case will an error message be issued.
 326
 327 The files are read in the order given above, with last value found taking
 328 precedence over values read earlier.  When multiple values are taken then all
 329 values of a key from all files will be used.
 330
 331 You may override individual configuration parameters when running any git
 332 command by using the `-c` option. See linkgit:git[1] for details.
 333
 334 All writing options will per default write to the repository specific
 335 configuration file. Note that this also affects options like `--replace-all`
 336 and `--unset`. *'git config' will only ever change one file at a time*.
 337
 338 You can override these rules using the `--global`, `--system`,
 339 `--local`, `--worktree`, and `--file` command-line options; see
 340 <<OPTIONS>> above.
 341
 342
 343 ENVIRONMENT
 344 -----------
 345
 346 GIT_CONFIG_GLOBAL::
 347 GIT_CONFIG_SYSTEM::
 348         Take the configuration from the given files instead from global or
 349         system-level configuration. See linkgit:git[1] for details.
 350
 351 GIT_CONFIG_NOSYSTEM::
 352         Whether to skip reading settings from the system-wide
 353         $(prefix)/etc/gitconfig file. See linkgit:git[1] for details.
 354
 355 See also <<FILES>>.
 356
 357 GIT_CONFIG_COUNT::
 358 GIT_CONFIG_KEY_<n>::
 359 GIT_CONFIG_VALUE_<n>::
 360         If GIT_CONFIG_COUNT is set to a positive number, all environment pairs
 361         GIT_CONFIG_KEY_<n> and GIT_CONFIG_VALUE_<n> up to that number will be
 362         added to the process's runtime configuration. The config pairs are
 363         zero-indexed. Any missing key or value is treated as an error. An empty
 364         GIT_CONFIG_COUNT is treated the same as GIT_CONFIG_COUNT=0, namely no
 365         pairs are processed. These environment variables will override values
 366         in configuration files, but will be overridden by any explicit options
 367         passed via `git -c`.
 368 +
 369 This is useful for cases where you want to spawn multiple git commands
 370 with a common configuration but cannot depend on a configuration file,
 371 for example when writing scripts.
 372
 373 GIT_CONFIG::
 374         If no `--file` option is provided to `git config`, use the file
 375         given by `GIT_CONFIG` as if it were provided via `--file`. This
 376         variable has no effect on other Git commands, and is mostly for
 377         historical compatibility; there is generally no reason to use it
 378         instead of the `--file` option.
 379
 380 [[EXAMPLES]]
 381 EXAMPLES
 382 --------
 383
 384 Given a .git/config like this:
 385
 386 ------------
 387 #
 388 # This is the config file, and
 389 # a '#' or ';' character indicates
 390 # a comment
 391 #
 392
 393 ; core variables
 394 [core]
 395         ; Don't trust file modes
 396         filemode = false
 397
 398 ; Our diff algorithm
 399 [diff]
 400         external = /usr/local/bin/diff-wrapper
 401         renames = true
 402
 403 ; Proxy settings
 404 [core]
 405         gitproxy=proxy-command for kernel.org
 406         gitproxy=default-proxy ; for all the rest
 407
 408 ; HTTP
 409 [http]
 410         sslVerify
 411 [http "https://weak.example.com"]
 412         sslVerify = false
 413         cookieFile = /tmp/cookie.txt
 414 ------------
 415
 416 you can set the filemode to true with
 417
 418 ------------
 419 % git config core.filemode true
 420 ------------
 421
 422 The hypothetical proxy command entries actually have a postfix to discern
 423 what URL they apply to. Here is how to change the entry for kernel.org
 424 to "ssh".
 425
 426 ------------
 427 % git config core.gitproxy '"ssh" for kernel.org' 'for kernel.org$'
 428 ------------
 429
 430 This makes sure that only the key/value pair for kernel.org is replaced.
 431
 432 To delete the entry for renames, do
 433
 434 ------------
 435 % git config --unset diff.renames
 436 ------------
 437
 438 If you want to delete an entry for a multivar (like core.gitproxy above),
 439 you have to provide a regex matching the value of exactly one line.
 440
 441 To query the value for a given key, do
 442
 443 ------------
 444 % git config --get core.filemode
 445 ------------
 446
 447 or
 448
 449 ------------
 450 % git config core.filemode
 451 ------------
 452
 453 or, to query a multivar:
 454
 455 ------------
 456 % git config --get core.gitproxy "for kernel.org$"
 457 ------------
 458
 459 If you want to know all the values for a multivar, do:
 460
 461 ------------
 462 % git config --get-all core.gitproxy
 463 ------------
 464
 465 If you like to live dangerously, you can replace *all* core.gitproxy by a
 466 new one with
 467
 468 ------------
 469 % git config --replace-all core.gitproxy ssh
 470 ------------
 471
 472 However, if you really only want to replace the line for the default proxy,
 473 i.e. the one without a "for ..." postfix, do something like this:
 474
 475 ------------
 476 % git config core.gitproxy ssh '! for '
 477 ------------
 478
 479 To actually match only values with an exclamation mark, you have to
 480
 481 ------------
 482 % git config section.key value '[!]'
 483 ------------
 484
 485 To add a new proxy, without altering any of the existing ones, use
 486
 487 ------------
 488 % git config --add core.gitproxy '"proxy-command" for example.com'
 489 ------------
 490
 491 An example to use customized color from the configuration in your
 492 script:
 493
 494 ------------
 495 #!/bin/sh
 496 WS=$(git config --get-color color.diff.whitespace "blue reverse")
 497 RESET=$(git config --get-color "" "reset")
 498 echo "${WS}your whitespace color or blue reverse${RESET}"
 499 ------------
 500
 501 For URLs in `https://weak.example.com`, `http.sslVerify` is set to
 502 false, while it is set to `true` for all others:
 503
 504 ------------
 505 % git config --type=bool --get-urlmatch http.sslverify https://good.example.com
 506 true
 507 % git config --type=bool --get-urlmatch http.sslverify https://weak.example.com
 508 false
 509 % git config --get-urlmatch http https://weak.example.com
 510 http.cookieFile /tmp/cookie.txt
 511 http.sslverify false
 512 ------------
 513
 514 include::config.txt[]
 515
 516 BUGS
 517 ----
 518 When using the deprecated `[section.subsection]` syntax, changing a value
 519 will result in adding a multi-line key instead of a change, if the subsection
 520 is given with at least one uppercase character. For example when the config
 521 looks like
 522
 523 --------
 524   [section.subsection]
 525     key = value1
 526 --------
 527
 528 and running `git config section.Subsection.key value2` will result in
 529
 530 --------
 531   [section.subsection]
 532     key = value1
 533     key = value2
 534 --------
 535
 536
 537 GIT
 538 ---
 539 Part of the linkgit:git[1] suite