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