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 expanding 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 By default, 'git config' will read configuration options from multiple
 301 files:
 302
 303 $(prefix)/etc/gitconfig::
 304         System-wide configuration file.
 305
 306 $XDG_CONFIG_HOME/git/config::
 307 ~/.gitconfig::
 308         User-specific configuration files. When the XDG_CONFIG_HOME environment
 309         variable is not set or empty, $HOME/.config/ is used as
 310         $XDG_CONFIG_HOME.
 311 +
 312 These are also called "global" configuration files. If both files exist, both
 313 files are read in the order given above.
 314
 315 $GIT_DIR/config::
 316         Repository specific configuration file.
 317
 318 $GIT_DIR/config.worktree::
 319         This is optional and is only searched when
 320         `extensions.worktreeConfig` is present in $GIT_DIR/config.
 321
 322 You may also provide additional configuration parameters when running any
 323 git command by using the `-c` option. See linkgit:git[1] for details.
 324
 325 Options will be read from all of these files that are available. If the
 326 global or the system-wide configuration files are missing or unreadable they
 327 will be ignored. If the repository configuration file is missing or unreadable,
 328 'git config' will exit with a non-zero error code. An error message is produced
 329 if the file is unreadable, but not if it is missing.
 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 By default, options are only written to the repository specific
 336 configuration file. Note that this also affects options like `--replace-all`
 337 and `--unset`. *'git config' will only ever change one file at a time*.
 338
 339 You can limit which configuration sources are read from or written to by
 340 specifying the path of a file with the `--file` option, or by specifying a
 341 configuration scope with `--system`, `--global`, `--local`, or `--worktree`.
 342 For more, see <<OPTIONS>> above.
 343
 344 [[SCOPES]]
 345 SCOPES
 346 ------
 347
 348 Each configuration source falls within a configuration scope. The scopes
 349 are:
 350
 351 system::
 352         $(prefix)/etc/gitconfig
 353
 354 global::
 355         $XDG_CONFIG_HOME/git/config
 356 +
 357 ~/.gitconfig
 358
 359 local::
 360         $GIT_DIR/config
 361
 362 worktree::
 363         $GIT_DIR/config.worktree
 364
 365 command::
 366         GIT_CONFIG_{COUNT,KEY,VALUE} environment variables (see <<ENVIRONMENT>>
 367         below)
 368 +
 369 the `-c` option
 370
 371 With the exception of 'command', each scope corresponds to a command line
 372 option: `--system`, `--global`, `--local`, `--worktree`.
 373
 374 When reading options, specifying a scope will only read options from the
 375 files within that scope. When writing options, specifying a scope will write
 376 to the files within that scope (instead of the repository specific
 377 configuration file). See <<OPTIONS>> above for a complete description.
 378
 379 Most configuration options are respected regardless of the scope it is
 380 defined in, but some options are only respected in certain scopes. See the
 381 respective option's documentation for the full details.
 382
 383 Protected configuration
 384 ~~~~~~~~~~~~~~~~~~~~~~~
 385
 386 Protected configuration refers to the 'system', 'global', and 'command' scopes.
 387 For security reasons, certain options are only respected when they are
 388 specified in protected configuration, and ignored otherwise.
 389
 390 Git treats these scopes as if they are controlled by the user or a trusted
 391 administrator. This is because an attacker who controls these scopes can do
 392 substantial harm without using Git, so it is assumed that the user's environment
 393 protects these scopes against attackers.
 394
 395 [[ENVIRONMENT]]
 396 ENVIRONMENT
 397 -----------
 398
 399 GIT_CONFIG_GLOBAL::
 400 GIT_CONFIG_SYSTEM::
 401         Take the configuration from the given files instead from global or
 402         system-level configuration. See linkgit:git[1] for details.
 403
 404 GIT_CONFIG_NOSYSTEM::
 405         Whether to skip reading settings from the system-wide
 406         $(prefix)/etc/gitconfig file. See linkgit:git[1] for details.
 407
 408 See also <<FILES>>.
 409
 410 GIT_CONFIG_COUNT::
 411 GIT_CONFIG_KEY_<n>::
 412 GIT_CONFIG_VALUE_<n>::
 413         If GIT_CONFIG_COUNT is set to a positive number, all environment pairs
 414         GIT_CONFIG_KEY_<n> and GIT_CONFIG_VALUE_<n> up to that number will be
 415         added to the process's runtime configuration. The config pairs are
 416         zero-indexed. Any missing key or value is treated as an error. An empty
 417         GIT_CONFIG_COUNT is treated the same as GIT_CONFIG_COUNT=0, namely no
 418         pairs are processed. These environment variables will override values
 419         in configuration files, but will be overridden by any explicit options
 420         passed via `git -c`.
 421 +
 422 This is useful for cases where you want to spawn multiple git commands
 423 with a common configuration but cannot depend on a configuration file,
 424 for example when writing scripts.
 425
 426 GIT_CONFIG::
 427         If no `--file` option is provided to `git config`, use the file
 428         given by `GIT_CONFIG` as if it were provided via `--file`. This
 429         variable has no effect on other Git commands, and is mostly for
 430         historical compatibility; there is generally no reason to use it
 431         instead of the `--file` option.
 432
 433 [[EXAMPLES]]
 434 EXAMPLES
 435 --------
 436
 437 Given a .git/config like this:
 438
 439 ------------
 440 #
 441 # This is the config file, and
 442 # a '#' or ';' character indicates
 443 # a comment
 444 #
 445
 446 ; core variables
 447 [core]
 448         ; Don't trust file modes
 449         filemode = false
 450
 451 ; Our diff algorithm
 452 [diff]
 453         external = /usr/local/bin/diff-wrapper
 454         renames = true
 455
 456 ; Proxy settings
 457 [core]
 458         gitproxy=proxy-command for kernel.org
 459         gitproxy=default-proxy ; for all the rest
 460
 461 ; HTTP
 462 [http]
 463         sslVerify
 464 [http "https://weak.example.com"]
 465         sslVerify = false
 466         cookieFile = /tmp/cookie.txt
 467 ------------
 468
 469 you can set the filemode to true with
 470
 471 ------------
 472 % git config core.filemode true
 473 ------------
 474
 475 The hypothetical proxy command entries actually have a postfix to discern
 476 what URL they apply to. Here is how to change the entry for kernel.org
 477 to "ssh".
 478
 479 ------------
 480 % git config core.gitproxy '"ssh" for kernel.org' 'for kernel.org$'
 481 ------------
 482
 483 This makes sure that only the key/value pair for kernel.org is replaced.
 484
 485 To delete the entry for renames, do
 486
 487 ------------
 488 % git config --unset diff.renames
 489 ------------
 490
 491 If you want to delete an entry for a multivar (like core.gitproxy above),
 492 you have to provide a regex matching the value of exactly one line.
 493
 494 To query the value for a given key, do
 495
 496 ------------
 497 % git config --get core.filemode
 498 ------------
 499
 500 or
 501
 502 ------------
 503 % git config core.filemode
 504 ------------
 505
 506 or, to query a multivar:
 507
 508 ------------
 509 % git config --get core.gitproxy "for kernel.org$"
 510 ------------
 511
 512 If you want to know all the values for a multivar, do:
 513
 514 ------------
 515 % git config --get-all core.gitproxy
 516 ------------
 517
 518 If you like to live dangerously, you can replace *all* core.gitproxy by a
 519 new one with
 520
 521 ------------
 522 % git config --replace-all core.gitproxy ssh
 523 ------------
 524
 525 However, if you really only want to replace the line for the default proxy,
 526 i.e. the one without a "for ..." postfix, do something like this:
 527
 528 ------------
 529 % git config core.gitproxy ssh '! for '
 530 ------------
 531
 532 To actually match only values with an exclamation mark, you have to
 533
 534 ------------
 535 % git config section.key value '[!]'
 536 ------------
 537
 538 To add a new proxy, without altering any of the existing ones, use
 539
 540 ------------
 541 % git config --add core.gitproxy '"proxy-command" for example.com'
 542 ------------
 543
 544 An example to use customized color from the configuration in your
 545 script:
 546
 547 ------------
 548 #!/bin/sh
 549 WS=$(git config --get-color color.diff.whitespace "blue reverse")
 550 RESET=$(git config --get-color "" "reset")
 551 echo "${WS}your whitespace color or blue reverse${RESET}"
 552 ------------
 553
 554 For URLs in `https://weak.example.com`, `http.sslVerify` is set to
 555 false, while it is set to `true` for all others:
 556
 557 ------------
 558 % git config --type=bool --get-urlmatch http.sslverify https://good.example.com
 559 true
 560 % git config --type=bool --get-urlmatch http.sslverify https://weak.example.com
 561 false
 562 % git config --get-urlmatch http https://weak.example.com
 563 http.cookieFile /tmp/cookie.txt
 564 http.sslverify false
 565 ------------
 566
 567 include::config.txt[]
 568
 569 BUGS
 570 ----
 571 When using the deprecated `[section.subsection]` syntax, changing a value
 572 will result in adding a multi-line key instead of a change, if the subsection
 573 is given with at least one uppercase character. For example when the config
 574 looks like
 575
 576 --------
 577   [section.subsection]
 578     key = value1
 579 --------
 580
 581 and running `git config section.Subsection.key value2` will result in
 582
 583 --------
 584   [section.subsection]
 585     key = value1
 586     key = value2
 587 --------
 588
 589
 590 GIT
 591 ---
 592 Part of the linkgit:git[1] suite