Git 2.24.2
[git] / Documentation / git-config.txt
1 git-config(1)
2 =============
3
4 NAME
5 ----
6 git-config - Get and set repository or global options
7
8
9 SYNOPSIS
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
28 DESCRIPTION
29 -----------
30 You can query/set/replace/unset options with this command. The name is
31 actually the section and the key separated by a dot, and the value will be
32 escaped.
33
34 Multiple lines can be added to an option by using the `--add` option.
35 If you want to update or unset an option which can occur on multiple
36 lines, a POSIX regexp `value_regex` needs to be given.  Only the
37 existing values that match the regexp are updated or unset.  If
38 you want to handle the lines that do *not* match the regex, just
39 prepend a single exclamation mark in front (see also <<EXAMPLES>>).
40
41 The `--type=<type>` option instructs 'git config' to ensure that incoming and
42 outgoing values are canonicalize-able under the given <type>.  If no
43 `--type=<type>` is given, no canonicalization will be performed. Callers may
44 unset an existing `--type` specifier with `--no-type`.
45
46 When reading, the values are read from the system, global and
47 repository 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
50 that location (see <<FILES>>).
51
52 When writing, the new value is written to the repository local
53 configuration file by default, and options `--system`, `--global`,
54 `--worktree`, `--file <filename>` can be used to tell the command to
55 write to that location (you can say `--local` but that is the
56 default).
57
58 This command will fail with non-zero status upon error.  Some exit
59 codes 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
69 On success, the command returns the exit code 0.
70
71 OPTIONS
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 +
112 For reading options: read only from global `~/.gitconfig` and from
113 `$XDG_CONFIG_HOME/git/config` rather than from all available files.
114 +
115 See 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 +
122 For reading options: read only from system-wide `$(prefix)/etc/gitconfig`
123 rather than from all available files.
124 +
125 See also <<FILES>>.
126
127 --local::
128         For writing options: write to the repository `.git/config` file.
129         This is the default behavior.
130 +
131 For reading options: read only from the repository `.git/config` rather than
132 from all available files.
133 +
134 See 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 +
173 Valid `<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
262 CONFIGURATION
263 -------------
264 `pager.config` is only respected when listing configuration, i.e., when
265 using `--list` or any of the `--get-*` which may return multiple results.
266 The default is to use a pager.
267
268 [[FILES]]
269 FILES
270 -----
271
272 If 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
297 If no further options are given, all reading options will read all of these
298 files that are available. If the global or the system-wide configuration
299 file are not available they will be ignored. If the repository configuration
300 file is not available or readable, 'git config' will exit with a non-zero
301 error code. However, in neither case will an error message be issued.
302
303 The files are read in the order given above, with last value found taking
304 precedence over values read earlier.  When multiple values are taken then all
305 values of a key from all files will be used.
306
307 You may override individual configuration parameters when running any git
308 command by using the `-c` option. See linkgit:git[1] for details.
309
310 All writing options will per default write to the repository specific
311 configuration file. Note that this also affects options like `--replace-all`
312 and `--unset`. *'git config' will only ever change one file at a time*.
313
314 You can override these rules either by command-line options or by environment
315 variables. The `--global`, `--system` and `--worktree` options will limit
316 the file used to the global, system-wide or per-worktree file respectively.
317 The `GIT_CONFIG` environment variable has a similar effect, but you
318 can specify any filename you want.
319
320
321 ENVIRONMENT
322 -----------
323
324 GIT_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
329 GIT_CONFIG_NOSYSTEM::
330         Whether to skip reading settings from the system-wide
331         $(prefix)/etc/gitconfig file. See linkgit:git[1] for details.
332
333 See also <<FILES>>.
334
335
336 [[EXAMPLES]]
337 EXAMPLES
338 --------
339
340 Given a .git/config like this:
341
342 ------------
343 #
344 # This is the config file, and
345 # a '#' or ';' character indicates
346 # a comment
347 #
348
349 ; core variables
350 [core]
351         ; Don't trust file modes
352         filemode = false
353
354 ; Our diff algorithm
355 [diff]
356         external = /usr/local/bin/diff-wrapper
357         renames = true
358
359 ; Proxy settings
360 [core]
361         gitproxy=proxy-command for kernel.org
362         gitproxy=default-proxy ; for all the rest
363
364 ; HTTP
365 [http]
366         sslVerify
367 [http "https://weak.example.com"]
368         sslVerify = false
369         cookieFile = /tmp/cookie.txt
370 ------------
371
372 you can set the filemode to true with
373
374 ------------
375 % git config core.filemode true
376 ------------
377
378 The hypothetical proxy command entries actually have a postfix to discern
379 what URL they apply to. Here is how to change the entry for kernel.org
380 to "ssh".
381
382 ------------
383 % git config core.gitproxy '"ssh" for kernel.org' 'for kernel.org$'
384 ------------
385
386 This makes sure that only the key/value pair for kernel.org is replaced.
387
388 To delete the entry for renames, do
389
390 ------------
391 % git config --unset diff.renames
392 ------------
393
394 If you want to delete an entry for a multivar (like core.gitproxy above),
395 you have to provide a regex matching the value of exactly one line.
396
397 To query the value for a given key, do
398
399 ------------
400 % git config --get core.filemode
401 ------------
402
403 or
404
405 ------------
406 % git config core.filemode
407 ------------
408
409 or, to query a multivar:
410
411 ------------
412 % git config --get core.gitproxy "for kernel.org$"
413 ------------
414
415 If you want to know all the values for a multivar, do:
416
417 ------------
418 % git config --get-all core.gitproxy
419 ------------
420
421 If you like to live dangerously, you can replace *all* core.gitproxy by a
422 new one with
423
424 ------------
425 % git config --replace-all core.gitproxy ssh
426 ------------
427
428 However, if you really only want to replace the line for the default proxy,
429 i.e. the one without a "for ..." postfix, do something like this:
430
431 ------------
432 % git config core.gitproxy ssh '! for '
433 ------------
434
435 To actually match only values with an exclamation mark, you have to
436
437 ------------
438 % git config section.key value '[!]'
439 ------------
440
441 To add a new proxy, without altering any of the existing ones, use
442
443 ------------
444 % git config --add core.gitproxy '"proxy-command" for example.com'
445 ------------
446
447 An example to use customized color from the configuration in your
448 script:
449
450 ------------
451 #!/bin/sh
452 WS=$(git config --get-color color.diff.whitespace "blue reverse")
453 RESET=$(git config --get-color "" "reset")
454 echo "${WS}your whitespace color or blue reverse${RESET}"
455 ------------
456
457 For URLs in `https://weak.example.com`, `http.sslVerify` is set to
458 false, while it is set to `true` for all others:
459
460 ------------
461 % git config --type=bool --get-urlmatch http.sslverify https://good.example.com
462 true
463 % git config --type=bool --get-urlmatch http.sslverify https://weak.example.com
464 false
465 % git config --get-urlmatch http https://weak.example.com
466 http.cookieFile /tmp/cookie.txt
467 http.sslverify false
468 ------------
469
470 include::config.txt[]
471
472 BUGS
473 ----
474 When using the deprecated `[section.subsection]` syntax, changing a value
475 will result in adding a multi-line key instead of a change, if the subsection
476 is given with at least one uppercase character. For example when the config
477 looks like
478
479 --------
480   [section.subsection]
481     key = value1
482 --------
483
484 and running `git config section.Subsection.key value2` will result in
485
486 --------
487   [section.subsection]
488     key = value1
489     key = value2
490 --------
491
492
493 GIT
494 ---
495 Part of the linkgit:git[1] suite