freshlybakedca.ke
Git fork
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 list' [<file-option>] [<display-option>] [--includes]
13'git config get' [<file-option>] [<display-option>] [--includes] [--all] [--regexp] [--value=<pattern>] [--fixed-value] [--default=<default>] [--url=<url>] <name>
14'git config set' [<file-option>] [--type=<type>] [--all] [--value=<pattern>] [--fixed-value] <name> <value>
15'git config unset' [<file-option>] [--all] [--value=<pattern>] [--fixed-value] <name>
16'git config rename-section' [<file-option>] <old-name> <new-name>
17'git config remove-section' [<file-option>] <name>
18'git config edit' [<file-option>]
19'git config' [<file-option>] --get-colorbool <name> [<stdout-is-tty>]
20
21DESCRIPTION
22-----------
23You can query/set/replace/unset options with this command. The name is
24actually the section and the key separated by a dot, and the value will be
25escaped.
26
27Multiple lines can be added to an option by using the `--append` option.
28If you want to update or unset an option which can occur on multiple
29lines, `--value=<pattern>` (which is an extended regular expression,
30unless the `--fixed-value` option is given) needs to be given. Only the
31existing values that match the pattern are updated or unset. If
32you want to handle the lines that do *not* match the pattern, just
33prepend a single exclamation mark in front (see also <<EXAMPLES>>),
34but note that this only works when the `--fixed-value` option is not
35in use.
36
37The `--type=<type>` option instructs 'git config' to ensure that incoming and
38outgoing values are canonicalize-able under the given <type>. If no
39`--type=<type>` is given, no canonicalization will be performed. Callers may
40unset an existing `--type` specifier with `--no-type`.
41
42When reading, the values are read from the system, global and
43repository local configuration files by default, and options
44`--system`, `--global`, `--local`, `--worktree` and
45`--file <filename>` can be used to tell the command to read from only
46that location (see <<FILES>>).
47
48When writing, the new value is written to the repository local
49configuration file by default, and options `--system`, `--global`,
50`--worktree`, `--file <filename>` can be used to tell the command to
51write to that location (you can say `--local` but that is the
52default).
53
54This command will fail with non-zero status upon error. Some exit
55codes are:
56
57- The section or key is invalid (ret=1),
58- no section or name was provided (ret=2),
59- the config file is invalid (ret=3),
60- the config file cannot be written (ret=4),
61- you try to unset an option which does not exist (ret=5),
62- you try to unset/set an option for which multiple lines match (ret=5), or
63- you try to use an invalid regexp (ret=6).
64
65On success, the command returns the exit code 0.
66
67A list of all available configuration variables can be obtained using the
68`git help --config` command.
69
70COMMANDS
71--------
72
73list::
74 List all variables set in config file, along with their values.
75
76get::
77 Emits the value of the specified key. If key is present multiple times
78 in the configuration, emits the last value. If `--all` is specified,
79 emits all values associated with key. Returns error code 1 if key is
80 not present.
81
82set::
83 Set value for one or more config options. By default, this command
84 refuses to write multi-valued config options. Passing `--all` will
85 replace all multi-valued config options with the new value, whereas
86 `--value=` will replace all config options whose values match the given
87 pattern.
88
89unset::
90 Unset value for one or more config options. By default, this command
91 refuses to unset multi-valued keys. Passing `--all` will unset all
92 multi-valued config options, whereas `--value` will unset all config
93 options whose values match the given pattern.
94
95rename-section::
96 Rename the given section to a new name.
97
98remove-section::
99 Remove the given section from the configuration file.
100
101edit::
102 Opens an editor to modify the specified config file; either
103 `--system`, `--global`, `--local` (default), `--worktree`, or
104 `--file <config-file>`.
105
106[[OPTIONS]]
107OPTIONS
108-------
109
110--replace-all::
111 Default behavior is to replace at most one line. This replaces
112 all lines matching the key (and optionally `--value=<pattern>`).
113
114--append::
115 Adds a new line to the option without altering any existing
116 values. This is the same as providing '--value=^$' in `set`.
117
118--comment <message>::
119 Append a comment at the end of new or modified lines.
120+
121If _<message>_ begins with one or more whitespaces followed
122by "#", it is used as-is. If it begins with "#", a space is
123prepended before it is used. Otherwise, a string " # " (a
124space followed by a hash followed by a space) is prepended
125to it. And the resulting string is placed immediately after
126the value defined for the variable. The _<message>_ must
127not contain linefeed characters (no multi-line comments are
128permitted).
129
130--all::
131 With `get`, return all values for a multi-valued key.
132
133--regexp::
134 With `get`, interpret the name as a regular expression. Regular
135 expression matching is currently case-sensitive and done against a
136 canonicalized version of the key in which section and variable names
137 are lowercased, but subsection names are not.
138
139--url=<URL>::
140 When given a two-part <name> as <section>.<key>, the value for
141 <section>.<URL>.<key> whose <URL> part matches the best to the
142 given URL is returned (if no such key exists, the value for
143 <section>.<key> is used as a fallback). When given just the
144 <section> as name, do so for all the keys in the section and
145 list them. Returns error code 1 if no value is found.
146
147--global::
148 For writing options: write to global `~/.gitconfig` file
149 rather than the repository `.git/config`, write to
150 `$XDG_CONFIG_HOME/git/config` file if this file exists and the
151 `~/.gitconfig` file doesn't.
152+
153For reading options: read only from global `~/.gitconfig` and from
154`$XDG_CONFIG_HOME/git/config` rather than from all available files.
155+
156See also <<FILES>>.
157
158--system::
159 For writing options: write to system-wide
160 `$(prefix)/etc/gitconfig` rather than the repository
161 `.git/config`.
162+
163For reading options: read only from system-wide `$(prefix)/etc/gitconfig`
164rather than from all available files.
165+
166See also <<FILES>>.
167
168--local::
169 For writing options: write to the repository `.git/config` file.
170 This is the default behavior.
171+
172For reading options: read only from the repository `.git/config` rather than
173from all available files.
174+
175See also <<FILES>>.
176
177--worktree::
178 Similar to `--local` except that `$GIT_DIR/config.worktree` is
179 read from or written to if `extensions.worktreeConfig` is
180 enabled. If not it's the same as `--local`. Note that `$GIT_DIR`
181 is equal to `$GIT_COMMON_DIR` for the main working tree, but is of
182 the form `$GIT_DIR/worktrees/<id>/` for other working trees. See
183 linkgit:git-worktree[1] to learn how to enable
184 `extensions.worktreeConfig`.
185
186-f <config-file>::
187--file <config-file>::
188 For writing options: write to the specified file rather than the
189 repository `.git/config`.
190+
191For reading options: read only from the specified file rather than from all
192available files.
193+
194See also <<FILES>>.
195
196--blob <blob>::
197 Similar to `--file` but use the given blob instead of a file. E.g.
198 you can use 'master:.gitmodules' to read values from the file
199 '.gitmodules' in the master branch. See "SPECIFYING REVISIONS"
200 section in linkgit:gitrevisions[7] for a more complete list of
201 ways to spell blob names.
202
203`--value=<pattern>`::
204`--no-value`::
205 With `get`, `set`, and `unset`, match only against
206 _<pattern>_. The pattern is an extended regular expression unless
207 `--fixed-value` is given.
208+
209Use `--no-value` to unset _<pattern>_.
210
211--fixed-value::
212 When used with `--value=<pattern>`, treat _<pattern>_ as
213 an exact string instead of a regular expression. This will restrict
214 the name/value pairs that are matched to only those where the value
215 is exactly equal to _<pattern>_.
216
217--type <type>::
218 'git config' will ensure that any input or output is valid under the given
219 type constraint(s), and will canonicalize outgoing values in `<type>`'s
220 canonical form.
221+
222Valid `<type>`'s include:
223+
224- 'bool': canonicalize values `true`, `yes`,`on`, and positive
225 numbers as "true", and values `false`, `no`, `off` and `0` as
226 "false".
227- 'int': canonicalize values as simple decimal numbers. An optional suffix of
228 'k', 'm', or 'g' will cause the value to be multiplied by 1024, 1048576, or
229 1073741824 upon input.
230- 'bool-or-int': canonicalize according to either 'bool' or 'int', as described
231 above.
232- 'path': canonicalize by expanding a leading `~` to the value of `$HOME` and
233 `~user` to the home directory for the specified user. This specifier has no
234 effect when setting the value (but you can use `git config section.variable
235 ~/` from the command line to let your shell do the expansion.)
236- 'expiry-date': canonicalize by converting from a fixed or relative date-string
237 to a timestamp. This specifier has no effect when setting the value.
238- 'color': When getting a value, canonicalize by converting to an ANSI color
239 escape sequence. When setting a value, a sanity-check is performed to ensure
240 that the given value is canonicalize-able as an ANSI color, but it is written
241 as-is.
242+
243
244--bool::
245--int::
246--bool-or-int::
247--path::
248--expiry-date::
249 Historical options for selecting a type specifier. Prefer instead `--type`
250 (see above).
251
252--no-type::
253 Un-sets the previously set type specifier (if one was previously set). This
254 option requests that 'git config' not canonicalize the retrieved variable.
255 `--no-type` has no effect without `--type=<type>` or `--<type>`.
256
257-z::
258--null::
259 For all options that output values and/or keys, always
260 end values with the null character (instead of a
261 newline). Use newline instead as a delimiter between
262 key and value. This allows for secure parsing of the
263 output without getting confused e.g. by values that
264 contain line breaks.
265
266--name-only::
267 Output only the names of config variables for `list` or
268 `get`.
269
270`--show-names`::
271`--no-show-names`::
272 With `get`, show config keys in addition to their values. The
273 default is `--no-show-names` unless `--url` is given and there
274 are no subsections in _<name>_.
275
276--show-origin::
277 Augment the output of all queried config options with the
278 origin type (file, standard input, blob, command line) and
279 the actual origin (config file path, ref, or blob id if
280 applicable).
281
282--show-scope::
283 Similar to `--show-origin` in that it augments the output of
284 all queried config options with the scope of that value
285 (worktree, local, global, system, command).
286
287--get-colorbool <name> [<stdout-is-tty>]::
288
289 Find the color setting for `<name>` (e.g. `color.diff`) and output
290 "true" or "false". `<stdout-is-tty>` should be either "true" or
291 "false", and is taken into account when configuration says
292 "auto". If `<stdout-is-tty>` is missing, then checks the standard
293 output of the command itself, and exits with status 0 if color
294 is to be used, or exits with status 1 otherwise.
295 When the color setting for `name` is undefined, the command uses
296 `color.ui` as fallback.
297
298--includes::
299--no-includes::
300 Respect `include.*` directives in config files when looking up
301 values. Defaults to `off` when a specific file is given (e.g.,
302 using `--file`, `--global`, etc) and `on` when searching all
303 config files.
304
305--default <value>::
306 When using `get`, and the requested variable is not found, behave as if
307 <value> were the value assigned to that variable.
308
309DEPRECATED MODES
310----------------
311
312The following modes have been deprecated in favor of subcommands. It is
313recommended to migrate to the new syntax.
314
315'git config <name>'::
316 Replaced by `git config get <name>`.
317
318'git config <name> <value> [<value-pattern>]'::
319 Replaced by `git config set [--value=<pattern>] <name> <value>`.
320
321-l::
322--list::
323 Replaced by `git config list`.
324
325--get <name> [<value-pattern>]::
326 Replaced by `git config get [--value=<pattern>] <name>`.
327
328--get-all <name> [<value-pattern>]::
329 Replaced by `git config get [--value=<pattern>] --all <name>`.
330
331--get-regexp <name-regexp>::
332 Replaced by `git config get --all --show-names --regexp <name-regexp>`.
333
334--get-urlmatch <name> <URL>::
335 Replaced by `git config get --all --show-names --url=<URL> <name>`.
336
337--get-color <name> [<default>]::
338 Replaced by `git config get --type=color [--default=<default>] <name>`.
339
340--add <name> <value>::
341 Replaced by `git config set --append <name> <value>`.
342
343--unset <name> [<value-pattern>]::
344 Replaced by `git config unset [--value=<pattern>] <name>`.
345
346--unset-all <name> [<value-pattern>]::
347 Replaced by `git config unset [--value=<pattern>] --all <name>`.
348
349--rename-section <old-name> <new-name>::
350 Replaced by `git config rename-section <old-name> <new-name>`.
351
352--remove-section <name>::
353 Replaced by `git config remove-section <name>`.
354
355-e::
356--edit::
357 Replaced by `git config edit`.
358
359CONFIGURATION
360-------------
361`pager.config` is only respected when listing configuration, i.e., when
362using `list` or `get` which may return multiple results. The default is to use
363a pager.
364
365[[FILES]]
366FILES
367-----
368
369By default, 'git config' will read configuration options from multiple
370files:
371
372$(prefix)/etc/gitconfig::
373 System-wide configuration file.
374
375$XDG_CONFIG_HOME/git/config::
376~/.gitconfig::
377 User-specific configuration files. When the XDG_CONFIG_HOME environment
378 variable is not set or empty, $HOME/.config/ is used as
379 $XDG_CONFIG_HOME.
380+
381These are also called "global" configuration files. If both files exist, both
382files are read in the order given above.
383
384$GIT_DIR/config::
385 Repository specific configuration file.
386
387$GIT_DIR/config.worktree::
388 This is optional and is only searched when
389 `extensions.worktreeConfig` is present in $GIT_DIR/config.
390
391You may also provide additional configuration parameters when running any
392git command by using the `-c` option. See linkgit:git[1] for details.
393
394Options will be read from all of these files that are available. If the
395global or the system-wide configuration files are missing or unreadable they
396will be ignored. If the repository configuration file is missing or unreadable,
397'git config' will exit with a non-zero error code. An error message is produced
398if the file is unreadable, but not if it is missing.
399
400The files are read in the order given above, with last value found taking
401precedence over values read earlier. When multiple values are taken then all
402values of a key from all files will be used.
403
404By default, options are only written to the repository specific
405configuration file. Note that this also affects options like `set`
406and `unset`. *'git config' will only ever change one file at a time*.
407
408You can limit which configuration sources are read from or written to by
409specifying the path of a file with the `--file` option, or by specifying a
410configuration scope with `--system`, `--global`, `--local`, or `--worktree`.
411For more, see <<OPTIONS>> above.
412
413[[SCOPES]]
414SCOPES
415------
416
417Each configuration source falls within a configuration scope. The scopes
418are:
419
420system::
421 $(prefix)/etc/gitconfig
422
423global::
424 $XDG_CONFIG_HOME/git/config
425+
426~/.gitconfig
427
428local::
429 $GIT_DIR/config
430
431worktree::
432 $GIT_DIR/config.worktree
433
434command::
435 GIT_CONFIG_{COUNT,KEY,VALUE} environment variables (see <<ENVIRONMENT>>
436 below)
437+
438the `-c` option
439
440With the exception of 'command', each scope corresponds to a command line
441option: `--system`, `--global`, `--local`, `--worktree`.
442
443When reading options, specifying a scope will only read options from the
444files within that scope. When writing options, specifying a scope will write
445to the files within that scope (instead of the repository specific
446configuration file). See <<OPTIONS>> above for a complete description.
447
448Most configuration options are respected regardless of the scope it is
449defined in, but some options are only respected in certain scopes. See the
450respective option's documentation for the full details.
451
452Protected configuration
453~~~~~~~~~~~~~~~~~~~~~~~
454
455Protected configuration refers to the 'system', 'global', and 'command' scopes.
456For security reasons, certain options are only respected when they are
457specified in protected configuration, and ignored otherwise.
458
459Git treats these scopes as if they are controlled by the user or a trusted
460administrator. This is because an attacker who controls these scopes can do
461substantial harm without using Git, so it is assumed that the user's environment
462protects these scopes against attackers.
463
464[[ENVIRONMENT]]
465ENVIRONMENT
466-----------
467
468GIT_CONFIG_GLOBAL::
469GIT_CONFIG_SYSTEM::
470 Take the configuration from the given files instead from global or
471 system-level configuration. See linkgit:git[1] for details.
472
473GIT_CONFIG_NOSYSTEM::
474 Whether to skip reading settings from the system-wide
475 $(prefix)/etc/gitconfig file. See linkgit:git[1] for details.
476
477See also <<FILES>>.
478
479GIT_CONFIG_COUNT::
480GIT_CONFIG_KEY_<n>::
481GIT_CONFIG_VALUE_<n>::
482 If GIT_CONFIG_COUNT is set to a positive number, all environment pairs
483 GIT_CONFIG_KEY_<n> and GIT_CONFIG_VALUE_<n> up to that number will be
484 added to the process's runtime configuration. The config pairs are
485 zero-indexed. Any missing key or value is treated as an error. An empty
486 GIT_CONFIG_COUNT is treated the same as GIT_CONFIG_COUNT=0, namely no
487 pairs are processed. These environment variables will override values
488 in configuration files, but will be overridden by any explicit options
489 passed via `git -c`.
490+
491This is useful for cases where you want to spawn multiple git commands
492with a common configuration but cannot depend on a configuration file,
493for example when writing scripts.
494
495GIT_CONFIG::
496 If no `--file` option is provided to `git config`, use the file
497 given by `GIT_CONFIG` as if it were provided via `--file`. This
498 variable has no effect on other Git commands, and is mostly for
499 historical compatibility; there is generally no reason to use it
500 instead of the `--file` option.
501
502[[EXAMPLES]]
503EXAMPLES
504--------
505
506Given a .git/config like this:
507
508------------
509#
510# This is the config file, and
511# a '#' or ';' character indicates
512# a comment
513#
514
515; core variables
516[core]
517 ; Don't trust file modes
518 filemode = false
519
520; Our diff algorithm
521[diff]
522 external = /usr/local/bin/diff-wrapper
523 renames = true
524
525; Proxy settings
526[core]
527 gitproxy=proxy-command for kernel.org
528 gitproxy=default-proxy ; for all the rest
529
530; HTTP
531[http]
532 sslVerify
533[http "https://weak.example.com"]
534 sslVerify = false
535 cookieFile = /tmp/cookie.txt
536------------
537
538you can set the filemode to true with
539
540------------
541% git config set core.filemode true
542------------
543
544The hypothetical proxy command entries actually have a postfix to discern
545what URL they apply to. Here is how to change the entry for kernel.org
546to "ssh".
547
548------------
549% git config set --value='for kernel.org$' core.gitproxy '"ssh" for kernel.org'
550------------
551
552This makes sure that only the key/value pair for kernel.org is replaced.
553
554To delete the entry for renames, do
555
556------------
557% git config unset diff.renames
558------------
559
560If you want to delete an entry for a multivar (like core.gitproxy above),
561you have to provide a regex matching the value of exactly one line.
562
563To query the value for a given key, do
564
565------------
566% git config get core.filemode
567------------
568
569or, to query a multivar:
570
571------------
572% git config get --value="for kernel.org$" core.gitproxy
573------------
574
575If you want to know all the values for a multivar, do:
576
577------------
578% git config get --all --show-names core.gitproxy
579------------
580
581If you like to live dangerously, you can replace *all* core.gitproxy by a
582new one with
583
584------------
585% git config set --all core.gitproxy ssh
586------------
587
588However, if you really only want to replace the line for the default proxy,
589i.e. the one without a "for ..." postfix, do something like this:
590
591------------
592% git config set --value='! for ' core.gitproxy ssh
593------------
594
595To actually match only values with an exclamation mark, you have to
596
597------------
598% git config set --value='[!]' section.key value
599------------
600
601To add a new proxy, without altering any of the existing ones, use
602
603------------
604% git config set --append core.gitproxy '"proxy-command" for example.com'
605------------
606
607An example to use customized color from the configuration in your
608script:
609
610------------
611#!/bin/sh
612WS=$(git config get --type=color --default="blue reverse" color.diff.whitespace)
613RESET=$(git config get --type=color --default="reset" "")
614echo "${WS}your whitespace color or blue reverse${RESET}"
615------------
616
617For URLs in `https://weak.example.com`, `http.sslVerify` is set to
618false, while it is set to `true` for all others:
619
620------------
621% git config get --type=bool --url=https://good.example.com http.sslverify
622true
623% git config get --type=bool --url=https://weak.example.com http.sslverify
624false
625% git config get --url=https://weak.example.com http
626http.cookieFile /tmp/cookie.txt
627http.sslverify false
628------------
629
630include::config.adoc[]
631
632BUGS
633----
634When using the deprecated `[section.subsection]` syntax, changing a value
635will result in adding a multi-line key instead of a change, if the subsection
636is given with at least one uppercase character. For example when the config
637looks like
638
639--------
640 [section.subsection]
641 key = value1
642--------
643
644and running `git config section.Subsection.key value2` will result in
645
646--------
647 [section.subsection]
648 key = value1
649 key = value2
650--------
651
652
653GIT
654---
655Part of the linkgit:git[1] suite