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