Documentation / git-config.txton commit chainlint: fix for core.autocrlf=true (1ce2b45)
   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- 'color': When getting a value, canonicalize by converting to an ANSI color
 181  escape sequence. When setting a value, a sanity-check is performed to ensure
 182  that the given value is canonicalize-able as an ANSI color, but it is written
 183  as-is.
 184+
 185
 186--bool::
 187--int::
 188--bool-or-int::
 189--path::
 190--expiry-date::
 191  Historical options for selecting a type specifier. Prefer instead `--type`,
 192  (see: above).
 193
 194--no-type::
 195  Un-sets the previously set type specifier (if one was previously set). This
 196  option requests that 'git config' not canonicalize the retrieved variable.
 197  `--no-type` has no effect without `--type=<type>` or `--<type>`.
 198
 199-z::
 200--null::
 201        For all options that output values and/or keys, always
 202        end values with the null character (instead of a
 203        newline). Use newline instead as a delimiter between
 204        key and value. This allows for secure parsing of the
 205        output without getting confused e.g. by values that
 206        contain line breaks.
 207
 208--name-only::
 209        Output only the names of config variables for `--list` or
 210        `--get-regexp`.
 211
 212--show-origin::
 213        Augment the output of all queried config options with the
 214        origin type (file, standard input, blob, command line) and
 215        the actual origin (config file path, ref, or blob id if
 216        applicable).
 217
 218--get-colorbool name [stdout-is-tty]::
 219
 220        Find the color setting for `name` (e.g. `color.diff`) and output
 221        "true" or "false".  `stdout-is-tty` should be either "true" or
 222        "false", and is taken into account when configuration says
 223        "auto".  If `stdout-is-tty` is missing, then checks the standard
 224        output of the command itself, and exits with status 0 if color
 225        is to be used, or exits with status 1 otherwise.
 226        When the color setting for `name` is undefined, the command uses
 227        `color.ui` as fallback.
 228
 229--get-color name [default]::
 230
 231        Find the color configured for `name` (e.g. `color.diff.new`) and
 232        output it as the ANSI color escape sequence to the standard
 233        output.  The optional `default` parameter is used instead, if
 234        there is no color configured for `name`.
 235+
 236`--type=color [--default=<default>]` is preferred over `--get-color`.
 237
 238-e::
 239--edit::
 240        Opens an editor to modify the specified config file; either
 241        `--system`, `--global`, or repository (default).
 242
 243--[no-]includes::
 244        Respect `include.*` directives in config files when looking up
 245        values. Defaults to `off` when a specific file is given (e.g.,
 246        using `--file`, `--global`, etc) and `on` when searching all
 247        config files.
 248
 249--default <value>::
 250  When using `--get`, and the requested variable is not found, behave as if
 251  <value> were the value assigned to the that variable.
 252
 253CONFIGURATION
 254-------------
 255`pager.config` is only respected when listing configuration, i.e., when
 256using `--list` or any of the `--get-*` which may return multiple results.
 257The default is to use a pager.
 258
 259[[FILES]]
 260FILES
 261-----
 262
 263If not set explicitly with `--file`, there are four files where
 264'git config' will search for configuration options:
 265
 266$(prefix)/etc/gitconfig::
 267        System-wide configuration file.
 268
 269$XDG_CONFIG_HOME/git/config::
 270        Second user-specific configuration file. If $XDG_CONFIG_HOME is not set
 271        or empty, `$HOME/.config/git/config` will be used. Any single-valued
 272        variable set in this file will be overwritten by whatever is in
 273        `~/.gitconfig`.  It is a good idea not to create this file if
 274        you sometimes use older versions of Git, as support for this
 275        file was added fairly recently.
 276
 277~/.gitconfig::
 278        User-specific configuration file. Also called "global"
 279        configuration file.
 280
 281$GIT_DIR/config::
 282        Repository specific configuration file.
 283
 284If no further options are given, all reading options will read all of these
 285files that are available. If the global or the system-wide configuration
 286file are not available they will be ignored. If the repository configuration
 287file is not available or readable, 'git config' will exit with a non-zero
 288error code. However, in neither case will an error message be issued.
 289
 290The files are read in the order given above, with last value found taking
 291precedence over values read earlier.  When multiple values are taken then all
 292values of a key from all files will be used.
 293
 294You may override individual configuration parameters when running any git
 295command by using the `-c` option. See linkgit:git[1] for details.
 296
 297All writing options will per default write to the repository specific
 298configuration file. Note that this also affects options like `--replace-all`
 299and `--unset`. *'git config' will only ever change one file at a time*.
 300
 301You can override these rules either by command-line options or by environment
 302variables. The `--global` and the `--system` options will limit the file used
 303to the global or system-wide file respectively. The `GIT_CONFIG` environment
 304variable has a similar effect, but you can specify any filename you want.
 305
 306
 307ENVIRONMENT
 308-----------
 309
 310GIT_CONFIG::
 311        Take the configuration from the given file instead of .git/config.
 312        Using the "--global" option forces this to ~/.gitconfig. Using the
 313        "--system" option forces this to $(prefix)/etc/gitconfig.
 314
 315GIT_CONFIG_NOSYSTEM::
 316        Whether to skip reading settings from the system-wide
 317        $(prefix)/etc/gitconfig file. See linkgit:git[1] for details.
 318
 319See also <<FILES>>.
 320
 321
 322[[EXAMPLES]]
 323EXAMPLES
 324--------
 325
 326Given a .git/config like this:
 327
 328        #
 329        # This is the config file, and
 330        # a '#' or ';' character indicates
 331        # a comment
 332        #
 333
 334        ; core variables
 335        [core]
 336                ; Don't trust file modes
 337                filemode = false
 338
 339        ; Our diff algorithm
 340        [diff]
 341                external = /usr/local/bin/diff-wrapper
 342                renames = true
 343
 344        ; Proxy settings
 345        [core]
 346                gitproxy=proxy-command for kernel.org
 347                gitproxy=default-proxy ; for all the rest
 348
 349        ; HTTP
 350        [http]
 351                sslVerify
 352        [http "https://weak.example.com"]
 353                sslVerify = false
 354                cookieFile = /tmp/cookie.txt
 355
 356you can set the filemode to true with
 357
 358------------
 359% git config core.filemode true
 360------------
 361
 362The hypothetical proxy command entries actually have a postfix to discern
 363what URL they apply to. Here is how to change the entry for kernel.org
 364to "ssh".
 365
 366------------
 367% git config core.gitproxy '"ssh" for kernel.org' 'for kernel.org$'
 368------------
 369
 370This makes sure that only the key/value pair for kernel.org is replaced.
 371
 372To delete the entry for renames, do
 373
 374------------
 375% git config --unset diff.renames
 376------------
 377
 378If you want to delete an entry for a multivar (like core.gitproxy above),
 379you have to provide a regex matching the value of exactly one line.
 380
 381To query the value for a given key, do
 382
 383------------
 384% git config --get core.filemode
 385------------
 386
 387or
 388
 389------------
 390% git config core.filemode
 391------------
 392
 393or, to query a multivar:
 394
 395------------
 396% git config --get core.gitproxy "for kernel.org$"
 397------------
 398
 399If you want to know all the values for a multivar, do:
 400
 401------------
 402% git config --get-all core.gitproxy
 403------------
 404
 405If you like to live dangerously, you can replace *all* core.gitproxy by a
 406new one with
 407
 408------------
 409% git config --replace-all core.gitproxy ssh
 410------------
 411
 412However, if you really only want to replace the line for the default proxy,
 413i.e. the one without a "for ..." postfix, do something like this:
 414
 415------------
 416% git config core.gitproxy ssh '! for '
 417------------
 418
 419To actually match only values with an exclamation mark, you have to
 420
 421------------
 422% git config section.key value '[!]'
 423------------
 424
 425To add a new proxy, without altering any of the existing ones, use
 426
 427------------
 428% git config --add core.gitproxy '"proxy-command" for example.com'
 429------------
 430
 431An example to use customized color from the configuration in your
 432script:
 433
 434------------
 435#!/bin/sh
 436WS=$(git config --get-color color.diff.whitespace "blue reverse")
 437RESET=$(git config --get-color "" "reset")
 438echo "${WS}your whitespace color or blue reverse${RESET}"
 439------------
 440
 441For URLs in `https://weak.example.com`, `http.sslVerify` is set to
 442false, while it is set to `true` for all others:
 443
 444------------
 445% git config --bool --get-urlmatch http.sslverify https://good.example.com
 446true
 447% git config --bool --get-urlmatch http.sslverify https://weak.example.com
 448false
 449% git config --get-urlmatch http https://weak.example.com
 450http.cookieFile /tmp/cookie.txt
 451http.sslverify false
 452------------
 453
 454include::config.txt[]
 455
 456GIT
 457---
 458Part of the linkgit:git[1] suite