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