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