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