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