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