]>
Commit | Line | Data |
---|---|---|
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 | All writing options will per default write to the repository specific | |
267 | configuration file. Note that this also affects options like '--replace-all' | |
268 | and '--unset'. *'git config' will only ever change one file at a time*. | |
269 | ||
270 | You can override these rules either by command-line options or by environment | |
271 | variables. The '--global' and the '--system' options will limit the file used | |
272 | to the global or system-wide file respectively. The `GIT_CONFIG` environment | |
273 | variable has a similar effect, but you can specify any filename you want. | |
274 | ||
275 | ||
276 | ENVIRONMENT | |
277 | ----------- | |
278 | ||
279 | GIT_CONFIG:: | |
280 | Take the configuration from the given file instead of .git/config. | |
281 | Using the "--global" option forces this to ~/.gitconfig. Using the | |
282 | "--system" option forces this to $(prefix)/etc/gitconfig. | |
283 | ||
284 | GIT_CONFIG_NOSYSTEM:: | |
285 | Whether to skip reading settings from the system-wide | |
286 | $(prefix)/etc/gitconfig file. See linkgit:git[1] for details. | |
287 | ||
288 | See also <<FILES>>. | |
289 | ||
290 | ||
291 | [[EXAMPLES]] | |
292 | EXAMPLES | |
293 | -------- | |
294 | ||
295 | Given a .git/config like this: | |
296 | ||
297 | # | |
298 | # This is the config file, and | |
299 | # a '#' or ';' character indicates | |
300 | # a comment | |
301 | # | |
302 | ||
303 | ; core variables | |
304 | [core] | |
305 | ; Don't trust file modes | |
306 | filemode = false | |
307 | ||
308 | ; Our diff algorithm | |
309 | [diff] | |
310 | external = /usr/local/bin/diff-wrapper | |
311 | renames = true | |
312 | ||
313 | ; Proxy settings | |
314 | [core] | |
315 | gitproxy=proxy-command for kernel.org | |
316 | gitproxy=default-proxy ; for all the rest | |
317 | ||
318 | ; HTTP | |
319 | [http] | |
320 | sslVerify | |
321 | [http "https://weak.example.com"] | |
322 | sslVerify = false | |
323 | cookieFile = /tmp/cookie.txt | |
324 | ||
325 | you can set the filemode to true with | |
326 | ||
327 | ------------ | |
328 | % git config core.filemode true | |
329 | ------------ | |
330 | ||
331 | The hypothetical proxy command entries actually have a postfix to discern | |
332 | what URL they apply to. Here is how to change the entry for kernel.org | |
333 | to "ssh". | |
334 | ||
335 | ------------ | |
336 | % git config core.gitproxy '"ssh" for kernel.org' 'for kernel.org$' | |
337 | ------------ | |
338 | ||
339 | This makes sure that only the key/value pair for kernel.org is replaced. | |
340 | ||
341 | To delete the entry for renames, do | |
342 | ||
343 | ------------ | |
344 | % git config --unset diff.renames | |
345 | ------------ | |
346 | ||
347 | If you want to delete an entry for a multivar (like core.gitproxy above), | |
348 | you have to provide a regex matching the value of exactly one line. | |
349 | ||
350 | To query the value for a given key, do | |
351 | ||
352 | ------------ | |
353 | % git config --get core.filemode | |
354 | ------------ | |
355 | ||
356 | or | |
357 | ||
358 | ------------ | |
359 | % git config core.filemode | |
360 | ------------ | |
361 | ||
362 | or, to query a multivar: | |
363 | ||
364 | ------------ | |
365 | % git config --get core.gitproxy "for kernel.org$" | |
366 | ------------ | |
367 | ||
368 | If you want to know all the values for a multivar, do: | |
369 | ||
370 | ------------ | |
371 | % git config --get-all core.gitproxy | |
372 | ------------ | |
373 | ||
374 | If you like to live dangerously, you can replace *all* core.gitproxy by a | |
375 | new one with | |
376 | ||
377 | ------------ | |
378 | % git config --replace-all core.gitproxy ssh | |
379 | ------------ | |
380 | ||
381 | However, if you really only want to replace the line for the default proxy, | |
382 | i.e. the one without a "for ..." postfix, do something like this: | |
383 | ||
384 | ------------ | |
385 | % git config core.gitproxy ssh '! for ' | |
386 | ------------ | |
387 | ||
388 | To actually match only values with an exclamation mark, you have to | |
389 | ||
390 | ------------ | |
391 | % git config section.key value '[!]' | |
392 | ------------ | |
393 | ||
394 | To add a new proxy, without altering any of the existing ones, use | |
395 | ||
396 | ------------ | |
397 | % git config --add core.gitproxy '"proxy-command" for example.com' | |
398 | ------------ | |
399 | ||
400 | An example to use customized color from the configuration in your | |
401 | script: | |
402 | ||
403 | ------------ | |
404 | #!/bin/sh | |
405 | WS=$(git config --get-color color.diff.whitespace "blue reverse") | |
406 | RESET=$(git config --get-color "" "reset") | |
407 | echo "${WS}your whitespace color or blue reverse${RESET}" | |
408 | ------------ | |
409 | ||
410 | For URLs in `https://weak.example.com`, `http.sslVerify` is set to | |
411 | false, while it is set to `true` for all others: | |
412 | ||
413 | ------------ | |
414 | % git config --bool --get-urlmatch http.sslverify https://good.example.com | |
415 | true | |
416 | % git config --bool --get-urlmatch http.sslverify https://weak.example.com | |
417 | false | |
418 | % git config --get-urlmatch http https://weak.example.com | |
419 | http.cookieFile /tmp/cookie.txt | |
420 | http.sslverify false | |
421 | ------------ | |
422 | ||
423 | include::config.txt[] | |
424 | ||
425 | GIT | |
426 | --- | |
427 | Part of the linkgit:git[1] suite |