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