]>
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] | |
b1889c36 JN |
12 | 'git config' [<file-option>] [type] [-z|--null] name [value [value_regex]] |
13 | 'git config' [<file-option>] [type] --add name value | |
bf71b4b3 | 14 | 'git config' [<file-option>] [type] --replace-all name value [value_regex] |
b1889c36 JN |
15 | 'git config' [<file-option>] [type] [-z|--null] --get name [value_regex] |
16 | 'git config' [<file-option>] [type] [-z|--null] --get-all name [value_regex] | |
17 | 'git config' [<file-option>] [type] [-z|--null] --get-regexp name_regex [value_regex] | |
18 | 'git config' [<file-option>] --unset name [value_regex] | |
19 | 'git config' [<file-option>] --unset-all name [value_regex] | |
20 | 'git config' [<file-option>] --rename-section old_name new_name | |
21 | 'git config' [<file-option>] --remove-section name | |
22 | 'git config' [<file-option>] [-z|--null] -l | --list | |
23 | 'git config' [<file-option>] --get-color name [default] | |
24 | 'git config' [<file-option>] --get-colorbool name [stdout-is-tty] | |
3bec8ff9 | 25 | 'git config' [<file-option>] -e | --edit |
e0d10e1c TP |
26 | |
27 | DESCRIPTION | |
28 | ----------- | |
29 | You can query/set/replace/unset options with this command. The name is | |
30 | actually the section and the key separated by a dot, and the value will be | |
31 | escaped. | |
32 | ||
33 | Multiple lines can be added to an option by using the '--add' option. | |
34 | If you want to update or unset an option which can occur on multiple | |
35 | lines, a POSIX regexp `value_regex` needs to be given. Only the | |
36 | existing values that match the regexp are updated or unset. If | |
37 | you want to handle the lines that do *not* match the regex, just | |
90a36e58 | 38 | prepend a single exclamation mark in front (see also <<EXAMPLES>>). |
e0d10e1c | 39 | |
1349484e | 40 | The type specifier can be either '--int' or '--bool', to make |
0b444cdb | 41 | 'git config' ensure that the variable(s) are of the given type and |
e0d10e1c | 42 | convert the value to the canonical form (simple decimal number for int, |
1349484e MM |
43 | a "true" or "false" string for bool), or '--path', which does some |
44 | path expansion (see '--path' below). If no type specifier is passed, no | |
45 | checks or transformations are performed on the value. | |
e0d10e1c | 46 | |
c598c5aa FA |
47 | When reading, the values are read from the system, global and |
48 | repository local configuration files by default, and options | |
49 | '--system', '--global', '--local' and '--file <filename>' can be | |
50 | used to tell the command to read from only 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 | '--file <filename>' can be used to tell the command to write to | |
55 | that location (you can say '--local' but that is the default). | |
be52a41c | 56 | |
9409c7a5 JH |
57 | This command will fail with non-zero status upon error. Some exit |
58 | codes are: | |
e0d10e1c | 59 | |
7a397419 MG |
60 | . The config file is invalid (ret=3), |
61 | . can not write to the config file (ret=4), | |
62 | . no section or name was provided (ret=2), | |
63 | . the section or key is invalid (ret=1), | |
64 | . you try to unset an option which does not exist (ret=5), | |
9409c7a5 JH |
65 | . you try to unset/set an option for which multiple lines match (ret=5), or |
66 | . you try to use an invalid regexp (ret=6). | |
e0d10e1c | 67 | |
7a397419 | 68 | On success, the command returns the exit code 0. |
e0d10e1c TP |
69 | |
70 | OPTIONS | |
71 | ------- | |
72 | ||
73 | --replace-all:: | |
74 | Default behavior is to replace at most one line. This replaces | |
75 | all lines matching the key (and optionally the value_regex). | |
76 | ||
77 | --add:: | |
78 | Adds a new line to the option without altering any existing | |
ac9f71cf FC |
79 | values. This is the same as providing '^$' as the value_regex |
80 | in `--replace-all`. | |
e0d10e1c TP |
81 | |
82 | --get:: | |
83 | Get the value for a given key (optionally filtered by a regex | |
84 | matching the value). Returns error code 1 if the key was not | |
85 | found and error code 2 if multiple key values were found. | |
86 | ||
87 | --get-all:: | |
88 | Like get, but does not fail if the number of values for the key | |
89 | is not exactly one. | |
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 TP |
97 | |
98 | --global:: | |
17014090 | 99 | For writing options: write to global ~/.gitconfig file rather than |
0e8593dc HKNN |
100 | the repository .git/config, write to $XDG_CONFIG_HOME/git/config file |
101 | if this file exists and the ~/.gitconfig file doesn't. | |
17014090 | 102 | + |
21cf3227 HKNN |
103 | For reading options: read only from global ~/.gitconfig and from |
104 | $XDG_CONFIG_HOME/git/config rather than from all available files. | |
17014090 FL |
105 | + |
106 | See also <<FILES>>. | |
e0d10e1c | 107 | |
9bc20aa7 | 108 | --system:: |
17014090 FL |
109 | For writing options: write to system-wide $(prefix)/etc/gitconfig |
110 | rather than the repository .git/config. | |
111 | + | |
112 | For reading options: read only from system-wide $(prefix)/etc/gitconfig | |
113 | rather than from all available files. | |
114 | + | |
115 | See also <<FILES>>. | |
9bc20aa7 | 116 | |
3240240f SB |
117 | -f config-file:: |
118 | --file config-file:: | |
67d454fe AR |
119 | Use the given config file instead of the one specified by GIT_CONFIG. |
120 | ||
118f8b24 PB |
121 | --remove-section:: |
122 | Remove the given section from the configuration file. | |
123 | ||
124 | --rename-section:: | |
125 | Rename the given section to a new name. | |
126 | ||
e0d10e1c TP |
127 | --unset:: |
128 | Remove the line matching the key from config file. | |
129 | ||
130 | --unset-all:: | |
9debca9a | 131 | Remove all lines matching the key from config file. |
e0d10e1c | 132 | |
3240240f SB |
133 | -l:: |
134 | --list:: | |
e0d10e1c TP |
135 | List all variables set in config file. |
136 | ||
137 | --bool:: | |
0b444cdb | 138 | 'git config' will ensure that the output is "true" or "false" |
e0d10e1c TP |
139 | |
140 | --int:: | |
0b444cdb | 141 | 'git config' will ensure that the output is a simple |
e0d10e1c TP |
142 | decimal number. An optional value suffix of 'k', 'm', or 'g' |
143 | in the config file will cause the value to be multiplied | |
144 | by 1024, 1048576, or 1073741824 prior to output. | |
145 | ||
d57f07eb | 146 | --bool-or-int:: |
0b444cdb | 147 | 'git config' will ensure that the output matches the format of |
d57f07eb JK |
148 | either --bool or --int, as described above. |
149 | ||
1349484e MM |
150 | --path:: |
151 | 'git-config' will expand leading '{tilde}' to the value of | |
152 | '$HOME', and '{tilde}user' to the home directory for the | |
153 | specified user. This option has no effect when setting the | |
154 | value (but you can use 'git config bla {tilde}/' from the | |
155 | command line to let your shell do the expansion). | |
156 | ||
3240240f SB |
157 | -z:: |
158 | --null:: | |
2275d502 | 159 | For all options that output values and/or keys, always |
a5d86f74 | 160 | end values with the null character (instead of a |
2275d502 FL |
161 | newline). Use newline instead as a delimiter between |
162 | key and value. This allows for secure parsing of the | |
163 | output without getting confused e.g. by values that | |
164 | contain line breaks. | |
165 | ||
0f6f5a40 JH |
166 | --get-colorbool name [stdout-is-tty]:: |
167 | ||
168 | Find the color setting for `name` (e.g. `color.diff`) and output | |
169 | "true" or "false". `stdout-is-tty` should be either "true" or | |
170 | "false", and is taken into account when configuration says | |
171 | "auto". If `stdout-is-tty` is missing, then checks the standard | |
172 | output of the command itself, and exits with status 0 if color | |
173 | is to be used, or exits with status 1 otherwise. | |
4d4f5ba3 MK |
174 | When the color setting for `name` is undefined, the command uses |
175 | `color.ui` as fallback. | |
0f6f5a40 | 176 | |
ac9f71cf | 177 | --get-color name [default]:: |
9ce03522 JH |
178 | |
179 | Find the color configured for `name` (e.g. `color.diff.new`) and | |
180 | output it as the ANSI color escape sequence to the standard | |
181 | output. The optional `default` parameter is used instead, if | |
182 | there is no color configured for `name`. | |
e0d10e1c | 183 | |
3bec8ff9 FC |
184 | -e:: |
185 | --edit:: | |
186 | Opens an editor to modify the specified config file; either | |
187 | '--system', '--global', or repository (default). | |
188 | ||
9b25a0b5 JK |
189 | --includes:: |
190 | --no-includes:: | |
191 | Respect `include.*` directives in config files when looking up | |
192 | values. Defaults to on. | |
193 | ||
17014090 FL |
194 | [[FILES]] |
195 | FILES | |
196 | ----- | |
197 | ||
21cf3227 | 198 | If not set explicitly with '--file', there are four files where |
0b444cdb | 199 | 'git config' will search for configuration options: |
17014090 | 200 | |
7c8b5eaf | 201 | $GIT_DIR/config:: |
ec84e069 | 202 | Repository specific configuration file. |
17014090 FL |
203 | |
204 | ~/.gitconfig:: | |
205 | User-specific configuration file. Also called "global" | |
206 | configuration file. | |
207 | ||
21cf3227 HKNN |
208 | $XDG_CONFIG_HOME/git/config:: |
209 | Second user-specific configuration file. If $XDG_CONFIG_HOME is not set | |
210 | or empty, $HOME/.config/git/config will be used. Any single-valued | |
211 | variable set in this file will be overwritten by whatever is in | |
212 | ~/.gitconfig. It is a good idea not to create this file if | |
213 | you sometimes use older versions of Git, as support for this | |
214 | file was added fairly recently. | |
215 | ||
17014090 FL |
216 | $(prefix)/etc/gitconfig:: |
217 | System-wide configuration file. | |
218 | ||
219 | If no further options are given, all reading options will read all of these | |
220 | files that are available. If the global or the system-wide configuration | |
221 | file are not available they will be ignored. If the repository configuration | |
0b444cdb | 222 | file is not available or readable, 'git config' will exit with a non-zero |
17014090 FL |
223 | error code. However, in neither case will an error message be issued. |
224 | ||
225 | All writing options will per default write to the repository specific | |
226 | configuration file. Note that this also affects options like '--replace-all' | |
0b444cdb | 227 | and '--unset'. *'git config' will only ever change one file at a time*. |
17014090 FL |
228 | |
229 | You can override these rules either by command line options or by environment | |
230 | variables. The '--global' and the '--system' options will limit the file used | |
231 | to the global or system-wide file respectively. The GIT_CONFIG environment | |
232 | variable has a similar effect, but you can specify any filename you want. | |
233 | ||
17014090 | 234 | |
e0d10e1c TP |
235 | ENVIRONMENT |
236 | ----------- | |
237 | ||
238 | GIT_CONFIG:: | |
239 | Take the configuration from the given file instead of .git/config. | |
17014090 FL |
240 | Using the "--global" option forces this to ~/.gitconfig. Using the |
241 | "--system" option forces this to $(prefix)/etc/gitconfig. | |
e0d10e1c | 242 | |
e8ef401c JN |
243 | GIT_CONFIG_NOSYSTEM:: |
244 | Whether to skip reading settings from the system-wide | |
245 | $(prefix)/etc/gitconfig file. See linkgit:git[1] for details. | |
246 | ||
17014090 | 247 | See also <<FILES>>. |
e0d10e1c | 248 | |
90a36e58 FL |
249 | |
250 | [[EXAMPLES]] | |
251 | EXAMPLES | |
252 | -------- | |
e0d10e1c TP |
253 | |
254 | Given a .git/config like this: | |
255 | ||
256 | # | |
257 | # This is the config file, and | |
258 | # a '#' or ';' character indicates | |
259 | # a comment | |
260 | # | |
261 | ||
262 | ; core variables | |
263 | [core] | |
264 | ; Don't trust file modes | |
265 | filemode = false | |
266 | ||
267 | ; Our diff algorithm | |
268 | [diff] | |
6bb9e51b | 269 | external = /usr/local/bin/diff-wrapper |
e0d10e1c TP |
270 | renames = true |
271 | ||
272 | ; Proxy settings | |
273 | [core] | |
d1e1fe75 | 274 | gitproxy=proxy-command for kernel.org |
e0d10e1c TP |
275 | gitproxy=default-proxy ; for all the rest |
276 | ||
277 | you can set the filemode to true with | |
278 | ||
279 | ------------ | |
280 | % git config core.filemode true | |
281 | ------------ | |
282 | ||
283 | The hypothetical proxy command entries actually have a postfix to discern | |
284 | what URL they apply to. Here is how to change the entry for kernel.org | |
285 | to "ssh". | |
286 | ||
287 | ------------ | |
288 | % git config core.gitproxy '"ssh" for kernel.org' 'for kernel.org$' | |
289 | ------------ | |
290 | ||
291 | This makes sure that only the key/value pair for kernel.org is replaced. | |
292 | ||
293 | To delete the entry for renames, do | |
294 | ||
295 | ------------ | |
296 | % git config --unset diff.renames | |
297 | ------------ | |
298 | ||
299 | If you want to delete an entry for a multivar (like core.gitproxy above), | |
300 | you have to provide a regex matching the value of exactly one line. | |
301 | ||
302 | To query the value for a given key, do | |
303 | ||
304 | ------------ | |
305 | % git config --get core.filemode | |
306 | ------------ | |
307 | ||
308 | or | |
309 | ||
310 | ------------ | |
311 | % git config core.filemode | |
312 | ------------ | |
313 | ||
314 | or, to query a multivar: | |
315 | ||
316 | ------------ | |
317 | % git config --get core.gitproxy "for kernel.org$" | |
318 | ------------ | |
319 | ||
320 | If you want to know all the values for a multivar, do: | |
321 | ||
322 | ------------ | |
323 | % git config --get-all core.gitproxy | |
324 | ------------ | |
325 | ||
544ddb04 | 326 | If you like to live dangerously, you can replace *all* core.gitproxy by a |
e0d10e1c TP |
327 | new one with |
328 | ||
329 | ------------ | |
330 | % git config --replace-all core.gitproxy ssh | |
331 | ------------ | |
332 | ||
333 | However, if you really only want to replace the line for the default proxy, | |
334 | i.e. the one without a "for ..." postfix, do something like this: | |
335 | ||
336 | ------------ | |
337 | % git config core.gitproxy ssh '! for ' | |
338 | ------------ | |
339 | ||
340 | To actually match only values with an exclamation mark, you have to | |
341 | ||
342 | ------------ | |
343 | % git config section.key value '[!]' | |
344 | ------------ | |
345 | ||
346 | To add a new proxy, without altering any of the existing ones, use | |
347 | ||
348 | ------------ | |
d0714cc8 | 349 | % git config --add core.gitproxy '"proxy-command" for example.com' |
e0d10e1c TP |
350 | ------------ |
351 | ||
9ce03522 JH |
352 | An example to use customized color from the configuration in your |
353 | script: | |
354 | ||
355 | ------------ | |
356 | #!/bin/sh | |
357 | WS=$(git config --get-color color.diff.whitespace "blue reverse") | |
358 | RESET=$(git config --get-color "" "reset") | |
359 | echo "${WS}your whitespace color or blue reverse${RESET}" | |
360 | ------------ | |
e0d10e1c TP |
361 | |
362 | include::config.txt[] | |
363 | ||
e0d10e1c TP |
364 | GIT |
365 | --- | |
9e1f0a85 | 366 | Part of the linkgit:git[1] suite |