]>
Commit | Line | Data |
---|---|---|
e0d10e1c TP |
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] | |
145d59f4 | 12 | 'git config' [<file-option>] [--type=<type>] [--show-origin] [--show-scope] [-z|--null] name [value [value_regex]] |
fb0dc3ba TB |
13 | 'git config' [<file-option>] [--type=<type>] --add name value |
14 | 'git config' [<file-option>] [--type=<type>] --replace-all name value [value_regex] | |
145d59f4 MR |
15 | 'git config' [<file-option>] [--type=<type>] [--show-origin] [--show-scope] [-z|--null] --get name [value_regex] |
16 | 'git config' [<file-option>] [--type=<type>] [--show-origin] [--show-scope] [-z|--null] --get-all name [value_regex] | |
17 | 'git config' [<file-option>] [--type=<type>] [--show-origin] [--show-scope] [-z|--null] [--name-only] --get-regexp name_regex [value_regex] | |
fb0dc3ba | 18 | 'git config' [<file-option>] [--type=<type>] [-z|--null] --get-urlmatch name URL |
b1889c36 JN |
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 | |
145d59f4 | 23 | 'git config' [<file-option>] [--show-origin] [--show-scope] [-z|--null] [--name-only] -l | --list |
b1889c36 JN |
24 | 'git config' [<file-option>] --get-color name [default] |
25 | 'git config' [<file-option>] --get-colorbool name [stdout-is-tty] | |
3bec8ff9 | 26 | 'git config' [<file-option>] -e | --edit |
e0d10e1c TP |
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 | ||
bcf9626a | 34 | Multiple lines can be added to an option by using the `--add` option. |
e0d10e1c TP |
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 | |
90a36e58 | 39 | prepend a single exclamation mark in front (see also <<EXAMPLES>>). |
e0d10e1c | 40 | |
fb0dc3ba TB |
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`. | |
e0d10e1c | 45 | |
c598c5aa FA |
46 | When reading, the values are read from the system, global and |
47 | repository local configuration files by default, and options | |
58b284a2 NTND |
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>>). | |
c598c5aa FA |
51 | |
52 | When writing, the new value is written to the repository local | |
bcf9626a | 53 | configuration file by default, and options `--system`, `--global`, |
58b284a2 NTND |
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). | |
be52a41c | 57 | |
9409c7a5 JH |
58 | This command will fail with non-zero status upon error. Some exit |
59 | codes are: | |
e0d10e1c | 60 | |
376eb604 | 61 | - The section or key is invalid (ret=1), |
94c5b0e8 | 62 | - no section or name was provided (ret=2), |
376eb604 SB |
63 | - the config file is invalid (ret=3), |
64 | - the config file cannot be written (ret=4), | |
94c5b0e8 JK |
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). | |
e0d10e1c | 68 | |
7a397419 | 69 | On success, the command returns the exit code 0. |
e0d10e1c TP |
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 | |
ac9f71cf FC |
80 | values. This is the same as providing '^$' as the value_regex |
81 | in `--replace-all`. | |
e0d10e1c TP |
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 | |
62e91efa | 86 | found and the last value if multiple key values were found. |
e0d10e1c TP |
87 | |
88 | --get-all:: | |
24990b2f | 89 | Like get, but returns all values for a multi-valued key. |
e0d10e1c TP |
90 | |
91 | --get-regexp:: | |
e0a4aae8 LP |
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. | |
e0d10e1c | 97 | |
d4770964 JH |
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 | |
27b30be6 | 104 | list them. Returns error code 1 if no value is found. |
d4770964 | 105 | |
e0d10e1c | 106 | --global:: |
5ff0c0e8 RR |
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. | |
17014090 | 111 | + |
5ff0c0e8 RR |
112 | For reading options: read only from global `~/.gitconfig` and from |
113 | `$XDG_CONFIG_HOME/git/config` rather than from all available files. | |
17014090 FL |
114 | + |
115 | See also <<FILES>>. | |
e0d10e1c | 116 | |
9bc20aa7 | 117 | --system:: |
5ff0c0e8 RR |
118 | For writing options: write to system-wide |
119 | `$(prefix)/etc/gitconfig` rather than the repository | |
120 | `.git/config`. | |
17014090 | 121 | + |
5ff0c0e8 | 122 | For reading options: read only from system-wide `$(prefix)/etc/gitconfig` |
17014090 FL |
123 | rather than from all available files. |
124 | + | |
125 | See also <<FILES>>. | |
9bc20aa7 | 126 | |
560d4b86 | 127 | --local:: |
5ff0c0e8 | 128 | For writing options: write to the repository `.git/config` file. |
8d75a1d1 | 129 | This is the default behavior. |
560d4b86 | 130 | + |
5ff0c0e8 | 131 | For reading options: read only from the repository `.git/config` rather than |
560d4b86 NK |
132 | from all available files. |
133 | + | |
134 | See also <<FILES>>. | |
135 | ||
58b284a2 NTND |
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 | ||
3240240f SB |
141 | -f config-file:: |
142 | --file config-file:: | |
67d454fe AR |
143 | Use the given config file instead of the one specified by GIT_CONFIG. |
144 | ||
1bc88819 | 145 | --blob blob:: |
bcf9626a | 146 | Similar to `--file` but use the given blob instead of a file. E.g. |
1bc88819 HV |
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 | ||
118f8b24 PB |
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 | ||
e0d10e1c TP |
158 | --unset:: |
159 | Remove the line matching the key from config file. | |
160 | ||
161 | --unset-all:: | |
9debca9a | 162 | Remove all lines matching the key from config file. |
e0d10e1c | 163 | |
3240240f SB |
164 | -l:: |
165 | --list:: | |
578625fa | 166 | List all variables set in config file, along with their values. |
e0d10e1c | 167 | |
fb0dc3ba TB |
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. | |
63e2a0f8 TB |
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. | |
fb0dc3ba | 191 | + |
e0d10e1c | 192 | |
fb0dc3ba | 193 | --bool:: |
e0d10e1c | 194 | --int:: |
d57f07eb | 195 | --bool-or-int:: |
1349484e | 196 | --path:: |
5f967424 | 197 | --expiry-date:: |
08caa95a MÅ |
198 | Historical options for selecting a type specifier. Prefer instead `--type` |
199 | (see above). | |
fb0dc3ba TB |
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>`. | |
5f967424 | 205 | |
3240240f SB |
206 | -z:: |
207 | --null:: | |
2275d502 | 208 | For all options that output values and/or keys, always |
a5d86f74 | 209 | end values with the null character (instead of a |
2275d502 FL |
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 | ||
578625fa SG |
215 | --name-only:: |
216 | Output only the names of config variables for `--list` or | |
217 | `--get-regexp`. | |
218 | ||
70bd879a LS |
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 | ||
145d59f4 MR |
225 | --show-scope:: |
226 | Similar to `--show-origin` in that it augments the output of | |
227 | all queried config options with the scope of that value | |
228 | (local, global, system, command). | |
229 | ||
0f6f5a40 JH |
230 | --get-colorbool name [stdout-is-tty]:: |
231 | ||
232 | Find the color setting for `name` (e.g. `color.diff`) and output | |
233 | "true" or "false". `stdout-is-tty` should be either "true" or | |
234 | "false", and is taken into account when configuration says | |
235 | "auto". If `stdout-is-tty` is missing, then checks the standard | |
236 | output of the command itself, and exits with status 0 if color | |
237 | is to be used, or exits with status 1 otherwise. | |
4d4f5ba3 MK |
238 | When the color setting for `name` is undefined, the command uses |
239 | `color.ui` as fallback. | |
0f6f5a40 | 240 | |
ac9f71cf | 241 | --get-color name [default]:: |
9ce03522 JH |
242 | |
243 | Find the color configured for `name` (e.g. `color.diff.new`) and | |
244 | output it as the ANSI color escape sequence to the standard | |
245 | output. The optional `default` parameter is used instead, if | |
246 | there is no color configured for `name`. | |
63e2a0f8 | 247 | + |
cd8e7593 JK |
248 | `--type=color [--default=<default>]` is preferred over `--get-color` |
249 | (but note that `--get-color` will omit the trailing newline printed by | |
250 | `--type=color`). | |
e0d10e1c | 251 | |
3bec8ff9 FC |
252 | -e:: |
253 | --edit:: | |
254 | Opens an editor to modify the specified config file; either | |
bcf9626a | 255 | `--system`, `--global`, or repository (default). |
3bec8ff9 | 256 | |
0460ed2c | 257 | --[no-]includes:: |
9b25a0b5 | 258 | Respect `include.*` directives in config files when looking up |
753a2cda JK |
259 | values. Defaults to `off` when a specific file is given (e.g., |
260 | using `--file`, `--global`, etc) and `on` when searching all | |
261 | config files. | |
9b25a0b5 | 262 | |
eeaa24b9 TB |
263 | --default <value>:: |
264 | When using `--get`, and the requested variable is not found, behave as if | |
265 | <value> were the value assigned to the that variable. | |
266 | ||
32888b8f MÅ |
267 | CONFIGURATION |
268 | ------------- | |
269 | `pager.config` is only respected when listing configuration, i.e., when | |
270 | using `--list` or any of the `--get-*` which may return multiple results. | |
c0e9f5be | 271 | The default is to use a pager. |
32888b8f | 272 | |
17014090 FL |
273 | [[FILES]] |
274 | FILES | |
275 | ----- | |
276 | ||
bcf9626a | 277 | If not set explicitly with `--file`, there are four files where |
0b444cdb | 278 | 'git config' will search for configuration options: |
17014090 | 279 | |
7da9800f JK |
280 | $(prefix)/etc/gitconfig:: |
281 | System-wide configuration file. | |
17014090 | 282 | |
21cf3227 HKNN |
283 | $XDG_CONFIG_HOME/git/config:: |
284 | Second user-specific configuration file. If $XDG_CONFIG_HOME is not set | |
5ff0c0e8 | 285 | or empty, `$HOME/.config/git/config` will be used. Any single-valued |
21cf3227 | 286 | variable set in this file will be overwritten by whatever is in |
5ff0c0e8 | 287 | `~/.gitconfig`. It is a good idea not to create this file if |
21cf3227 HKNN |
288 | you sometimes use older versions of Git, as support for this |
289 | file was added fairly recently. | |
290 | ||
7da9800f JK |
291 | ~/.gitconfig:: |
292 | User-specific configuration file. Also called "global" | |
293 | configuration file. | |
294 | ||
295 | $GIT_DIR/config:: | |
296 | Repository specific configuration file. | |
17014090 | 297 | |
58b284a2 NTND |
298 | $GIT_DIR/config.worktree:: |
299 | This is optional and is only searched when | |
300 | `extensions.worktreeConfig` is present in $GIT_DIR/config. | |
301 | ||
17014090 FL |
302 | If no further options are given, all reading options will read all of these |
303 | files that are available. If the global or the system-wide configuration | |
304 | file are not available they will be ignored. If the repository configuration | |
0b444cdb | 305 | file is not available or readable, 'git config' will exit with a non-zero |
17014090 FL |
306 | error code. However, in neither case will an error message be issued. |
307 | ||
7da9800f JK |
308 | The files are read in the order given above, with last value found taking |
309 | precedence over values read earlier. When multiple values are taken then all | |
310 | values of a key from all files will be used. | |
311 | ||
ae1f7094 DG |
312 | You may override individual configuration parameters when running any git |
313 | command by using the `-c` option. See linkgit:git[1] for details. | |
314 | ||
17014090 | 315 | All writing options will per default write to the repository specific |
bcf9626a MM |
316 | configuration file. Note that this also affects options like `--replace-all` |
317 | and `--unset`. *'git config' will only ever change one file at a time*. | |
17014090 | 318 | |
06ab60c0 | 319 | You can override these rules either by command-line options or by environment |
58b284a2 NTND |
320 | variables. The `--global`, `--system` and `--worktree` options will limit |
321 | the file used to the global, system-wide or per-worktree file respectively. | |
322 | The `GIT_CONFIG` environment variable has a similar effect, but you | |
323 | can specify any filename you want. | |
17014090 | 324 | |
17014090 | 325 | |
e0d10e1c TP |
326 | ENVIRONMENT |
327 | ----------- | |
328 | ||
329 | GIT_CONFIG:: | |
330 | Take the configuration from the given file instead of .git/config. | |
17014090 FL |
331 | Using the "--global" option forces this to ~/.gitconfig. Using the |
332 | "--system" option forces this to $(prefix)/etc/gitconfig. | |
e0d10e1c | 333 | |
e8ef401c JN |
334 | GIT_CONFIG_NOSYSTEM:: |
335 | Whether to skip reading settings from the system-wide | |
336 | $(prefix)/etc/gitconfig file. See linkgit:git[1] for details. | |
337 | ||
17014090 | 338 | See also <<FILES>>. |
e0d10e1c | 339 | |
90a36e58 FL |
340 | |
341 | [[EXAMPLES]] | |
342 | EXAMPLES | |
343 | -------- | |
e0d10e1c TP |
344 | |
345 | Given a .git/config like this: | |
346 | ||
1925fe0c MÅ |
347 | ------------ |
348 | # | |
349 | # This is the config file, and | |
350 | # a '#' or ';' character indicates | |
351 | # a comment | |
352 | # | |
353 | ||
354 | ; core variables | |
355 | [core] | |
356 | ; Don't trust file modes | |
357 | filemode = false | |
358 | ||
359 | ; Our diff algorithm | |
360 | [diff] | |
361 | external = /usr/local/bin/diff-wrapper | |
362 | renames = true | |
363 | ||
364 | ; Proxy settings | |
365 | [core] | |
366 | gitproxy=proxy-command for kernel.org | |
367 | gitproxy=default-proxy ; for all the rest | |
368 | ||
369 | ; HTTP | |
370 | [http] | |
371 | sslVerify | |
372 | [http "https://weak.example.com"] | |
373 | sslVerify = false | |
374 | cookieFile = /tmp/cookie.txt | |
375 | ------------ | |
d4770964 | 376 | |
e0d10e1c TP |
377 | you can set the filemode to true with |
378 | ||
379 | ------------ | |
380 | % git config core.filemode true | |
381 | ------------ | |
382 | ||
383 | The hypothetical proxy command entries actually have a postfix to discern | |
384 | what URL they apply to. Here is how to change the entry for kernel.org | |
385 | to "ssh". | |
386 | ||
387 | ------------ | |
388 | % git config core.gitproxy '"ssh" for kernel.org' 'for kernel.org$' | |
389 | ------------ | |
390 | ||
391 | This makes sure that only the key/value pair for kernel.org is replaced. | |
392 | ||
393 | To delete the entry for renames, do | |
394 | ||
395 | ------------ | |
396 | % git config --unset diff.renames | |
397 | ------------ | |
398 | ||
399 | If you want to delete an entry for a multivar (like core.gitproxy above), | |
400 | you have to provide a regex matching the value of exactly one line. | |
401 | ||
402 | To query the value for a given key, do | |
403 | ||
404 | ------------ | |
405 | % git config --get core.filemode | |
406 | ------------ | |
407 | ||
408 | or | |
409 | ||
410 | ------------ | |
411 | % git config core.filemode | |
412 | ------------ | |
413 | ||
414 | or, to query a multivar: | |
415 | ||
416 | ------------ | |
417 | % git config --get core.gitproxy "for kernel.org$" | |
418 | ------------ | |
419 | ||
420 | If you want to know all the values for a multivar, do: | |
421 | ||
422 | ------------ | |
423 | % git config --get-all core.gitproxy | |
424 | ------------ | |
425 | ||
544ddb04 | 426 | If you like to live dangerously, you can replace *all* core.gitproxy by a |
e0d10e1c TP |
427 | new one with |
428 | ||
429 | ------------ | |
430 | % git config --replace-all core.gitproxy ssh | |
431 | ------------ | |
432 | ||
433 | However, if you really only want to replace the line for the default proxy, | |
434 | i.e. the one without a "for ..." postfix, do something like this: | |
435 | ||
436 | ------------ | |
437 | % git config core.gitproxy ssh '! for ' | |
438 | ------------ | |
439 | ||
440 | To actually match only values with an exclamation mark, you have to | |
441 | ||
442 | ------------ | |
443 | % git config section.key value '[!]' | |
444 | ------------ | |
445 | ||
446 | To add a new proxy, without altering any of the existing ones, use | |
447 | ||
448 | ------------ | |
d0714cc8 | 449 | % git config --add core.gitproxy '"proxy-command" for example.com' |
e0d10e1c TP |
450 | ------------ |
451 | ||
9ce03522 JH |
452 | An example to use customized color from the configuration in your |
453 | script: | |
454 | ||
455 | ------------ | |
456 | #!/bin/sh | |
457 | WS=$(git config --get-color color.diff.whitespace "blue reverse") | |
458 | RESET=$(git config --get-color "" "reset") | |
459 | echo "${WS}your whitespace color or blue reverse${RESET}" | |
460 | ------------ | |
e0d10e1c | 461 | |
d4770964 JH |
462 | For URLs in `https://weak.example.com`, `http.sslVerify` is set to |
463 | false, while it is set to `true` for all others: | |
464 | ||
465 | ------------ | |
ed3bb3df | 466 | % git config --type=bool --get-urlmatch http.sslverify https://good.example.com |
d4770964 | 467 | true |
ed3bb3df | 468 | % git config --type=bool --get-urlmatch http.sslverify https://weak.example.com |
d4770964 JH |
469 | false |
470 | % git config --get-urlmatch http https://weak.example.com | |
da0005b8 | 471 | http.cookieFile /tmp/cookie.txt |
d4770964 JH |
472 | http.sslverify false |
473 | ------------ | |
474 | ||
e0d10e1c TP |
475 | include::config.txt[] |
476 | ||
bff7df7a SB |
477 | BUGS |
478 | ---- | |
479 | When using the deprecated `[section.subsection]` syntax, changing a value | |
480 | will result in adding a multi-line key instead of a change, if the subsection | |
481 | is given with at least one uppercase character. For example when the config | |
482 | looks like | |
483 | ||
484 | -------- | |
485 | [section.subsection] | |
486 | key = value1 | |
487 | -------- | |
488 | ||
489 | and running `git config section.Subsection.key value2` will result in | |
490 | ||
491 | -------- | |
492 | [section.subsection] | |
493 | key = value1 | |
494 | key = value2 | |
495 | -------- | |
496 | ||
497 | ||
e0d10e1c TP |
498 | GIT |
499 | --- | |
9e1f0a85 | 500 | Part of the linkgit:git[1] suite |