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