]>
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 | |
14 | 'git config' [<file-option>] [type] --replace-all name [value [value_regex]] | |
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] | |
e0d10e1c TP |
25 | |
26 | DESCRIPTION | |
27 | ----------- | |
28 | You can query/set/replace/unset options with this command. The name is | |
29 | actually the section and the key separated by a dot, and the value will be | |
30 | escaped. | |
31 | ||
32 | Multiple lines can be added to an option by using the '--add' option. | |
33 | If you want to update or unset an option which can occur on multiple | |
34 | lines, a POSIX regexp `value_regex` needs to be given. Only the | |
35 | existing values that match the regexp are updated or unset. If | |
36 | you want to handle the lines that do *not* match the regex, just | |
90a36e58 | 37 | prepend a single exclamation mark in front (see also <<EXAMPLES>>). |
e0d10e1c TP |
38 | |
39 | The type specifier can be either '--int' or '--bool', which will make | |
ba020ef5 | 40 | 'git-config' ensure that the variable(s) are of the given type and |
e0d10e1c | 41 | convert the value to the canonical form (simple decimal number for int, |
db1696b8 | 42 | a "true" or "false" string for bool). If no type specifier is passed, |
e0d10e1c TP |
43 | no checks or transformations are performed on the value. |
44 | ||
be52a41c AR |
45 | The file-option can be one of '--system', '--global' or '--file' |
46 | which specify where the values will be read from or written to. | |
47 | The default is to assume the config file of the current repository, | |
48 | .git/config unless defined otherwise with GIT_DIR and GIT_CONFIG | |
49 | (see <<FILES>>). | |
50 | ||
e0d10e1c TP |
51 | This command will fail if: |
52 | ||
67d454fe AR |
53 | . The config file is invalid, |
54 | . Can not write to the config file, | |
e0d10e1c TP |
55 | . no section was provided, |
56 | . the section or key is invalid, | |
57 | . you try to unset an option which does not exist, | |
58 | . you try to unset/set an option for which multiple lines match, or | |
90a36e58 | 59 | . you use '--global' option without $HOME being properly set. |
e0d10e1c TP |
60 | |
61 | ||
62 | OPTIONS | |
63 | ------- | |
64 | ||
65 | --replace-all:: | |
66 | Default behavior is to replace at most one line. This replaces | |
67 | all lines matching the key (and optionally the value_regex). | |
68 | ||
69 | --add:: | |
70 | Adds a new line to the option without altering any existing | |
71 | values. This is the same as providing '^$' as the value_regex. | |
72 | ||
73 | --get:: | |
74 | Get the value for a given key (optionally filtered by a regex | |
75 | matching the value). Returns error code 1 if the key was not | |
76 | found and error code 2 if multiple key values were found. | |
77 | ||
78 | --get-all:: | |
79 | Like get, but does not fail if the number of values for the key | |
80 | is not exactly one. | |
81 | ||
82 | --get-regexp:: | |
83 | Like --get-all, but interprets the name as a regular expression. | |
e373bb73 | 84 | Also outputs the key names. |
e0d10e1c TP |
85 | |
86 | --global:: | |
17014090 FL |
87 | For writing options: write to global ~/.gitconfig file rather than |
88 | the repository .git/config. | |
89 | + | |
90 | For reading options: read only from global ~/.gitconfig rather than | |
91 | from all available files. | |
92 | + | |
93 | See also <<FILES>>. | |
e0d10e1c | 94 | |
9bc20aa7 | 95 | --system:: |
17014090 FL |
96 | For writing options: write to system-wide $(prefix)/etc/gitconfig |
97 | rather than the repository .git/config. | |
98 | + | |
99 | For reading options: read only from system-wide $(prefix)/etc/gitconfig | |
100 | rather than from all available files. | |
101 | + | |
102 | See also <<FILES>>. | |
9bc20aa7 | 103 | |
3240240f SB |
104 | -f config-file:: |
105 | --file config-file:: | |
67d454fe AR |
106 | Use the given config file instead of the one specified by GIT_CONFIG. |
107 | ||
118f8b24 PB |
108 | --remove-section:: |
109 | Remove the given section from the configuration file. | |
110 | ||
111 | --rename-section:: | |
112 | Rename the given section to a new name. | |
113 | ||
e0d10e1c TP |
114 | --unset:: |
115 | Remove the line matching the key from config file. | |
116 | ||
117 | --unset-all:: | |
9debca9a | 118 | Remove all lines matching the key from config file. |
e0d10e1c | 119 | |
3240240f SB |
120 | -l:: |
121 | --list:: | |
e0d10e1c TP |
122 | List all variables set in config file. |
123 | ||
124 | --bool:: | |
ba020ef5 | 125 | 'git-config' will ensure that the output is "true" or "false" |
e0d10e1c TP |
126 | |
127 | --int:: | |
ba020ef5 | 128 | 'git-config' will ensure that the output is a simple |
e0d10e1c TP |
129 | decimal number. An optional value suffix of 'k', 'm', or 'g' |
130 | in the config file will cause the value to be multiplied | |
131 | by 1024, 1048576, or 1073741824 prior to output. | |
132 | ||
3240240f SB |
133 | -z:: |
134 | --null:: | |
2275d502 | 135 | For all options that output values and/or keys, always |
a5d86f74 | 136 | end values with the null character (instead of a |
2275d502 FL |
137 | newline). Use newline instead as a delimiter between |
138 | key and value. This allows for secure parsing of the | |
139 | output without getting confused e.g. by values that | |
140 | contain line breaks. | |
141 | ||
0f6f5a40 JH |
142 | --get-colorbool name [stdout-is-tty]:: |
143 | ||
144 | Find the color setting for `name` (e.g. `color.diff`) and output | |
145 | "true" or "false". `stdout-is-tty` should be either "true" or | |
146 | "false", and is taken into account when configuration says | |
147 | "auto". If `stdout-is-tty` is missing, then checks the standard | |
148 | output of the command itself, and exits with status 0 if color | |
149 | is to be used, or exits with status 1 otherwise. | |
4d4f5ba3 MK |
150 | When the color setting for `name` is undefined, the command uses |
151 | `color.ui` as fallback. | |
0f6f5a40 | 152 | |
9ce03522 JH |
153 | --get-color name default:: |
154 | ||
155 | Find the color configured for `name` (e.g. `color.diff.new`) and | |
156 | output it as the ANSI color escape sequence to the standard | |
157 | output. The optional `default` parameter is used instead, if | |
158 | there is no color configured for `name`. | |
e0d10e1c | 159 | |
17014090 FL |
160 | [[FILES]] |
161 | FILES | |
162 | ----- | |
163 | ||
02783075 | 164 | If not set explicitly with '--file', there are three files where |
ba020ef5 | 165 | 'git-config' will search for configuration options: |
17014090 | 166 | |
7c8b5eaf | 167 | $GIT_DIR/config:: |
17014090 FL |
168 | Repository specific configuration file. (The filename is |
169 | of course relative to the repository root, not the working | |
170 | directory.) | |
171 | ||
172 | ~/.gitconfig:: | |
173 | User-specific configuration file. Also called "global" | |
174 | configuration file. | |
175 | ||
176 | $(prefix)/etc/gitconfig:: | |
177 | System-wide configuration file. | |
178 | ||
179 | If no further options are given, all reading options will read all of these | |
180 | files that are available. If the global or the system-wide configuration | |
181 | file are not available they will be ignored. If the repository configuration | |
ba020ef5 | 182 | file is not available or readable, 'git-config' will exit with a non-zero |
17014090 FL |
183 | error code. However, in neither case will an error message be issued. |
184 | ||
185 | All writing options will per default write to the repository specific | |
186 | configuration file. Note that this also affects options like '--replace-all' | |
ba020ef5 | 187 | and '--unset'. *'git-config' will only ever change one file at a time*. |
17014090 FL |
188 | |
189 | You can override these rules either by command line options or by environment | |
190 | variables. The '--global' and the '--system' options will limit the file used | |
191 | to the global or system-wide file respectively. The GIT_CONFIG environment | |
192 | variable has a similar effect, but you can specify any filename you want. | |
193 | ||
17014090 | 194 | |
e0d10e1c TP |
195 | ENVIRONMENT |
196 | ----------- | |
197 | ||
198 | GIT_CONFIG:: | |
199 | Take the configuration from the given file instead of .git/config. | |
17014090 FL |
200 | Using the "--global" option forces this to ~/.gitconfig. Using the |
201 | "--system" option forces this to $(prefix)/etc/gitconfig. | |
e0d10e1c | 202 | |
17014090 | 203 | See also <<FILES>>. |
e0d10e1c | 204 | |
90a36e58 FL |
205 | |
206 | [[EXAMPLES]] | |
207 | EXAMPLES | |
208 | -------- | |
e0d10e1c TP |
209 | |
210 | Given a .git/config like this: | |
211 | ||
212 | # | |
213 | # This is the config file, and | |
214 | # a '#' or ';' character indicates | |
215 | # a comment | |
216 | # | |
217 | ||
218 | ; core variables | |
219 | [core] | |
220 | ; Don't trust file modes | |
221 | filemode = false | |
222 | ||
223 | ; Our diff algorithm | |
224 | [diff] | |
6bb9e51b | 225 | external = /usr/local/bin/diff-wrapper |
e0d10e1c TP |
226 | renames = true |
227 | ||
228 | ; Proxy settings | |
229 | [core] | |
e0d10e1c | 230 | gitproxy="proxy-command" for kernel.org |
e0d10e1c TP |
231 | gitproxy=default-proxy ; for all the rest |
232 | ||
233 | you can set the filemode to true with | |
234 | ||
235 | ------------ | |
236 | % git config core.filemode true | |
237 | ------------ | |
238 | ||
239 | The hypothetical proxy command entries actually have a postfix to discern | |
240 | what URL they apply to. Here is how to change the entry for kernel.org | |
241 | to "ssh". | |
242 | ||
243 | ------------ | |
244 | % git config core.gitproxy '"ssh" for kernel.org' 'for kernel.org$' | |
245 | ------------ | |
246 | ||
247 | This makes sure that only the key/value pair for kernel.org is replaced. | |
248 | ||
249 | To delete the entry for renames, do | |
250 | ||
251 | ------------ | |
252 | % git config --unset diff.renames | |
253 | ------------ | |
254 | ||
255 | If you want to delete an entry for a multivar (like core.gitproxy above), | |
256 | you have to provide a regex matching the value of exactly one line. | |
257 | ||
258 | To query the value for a given key, do | |
259 | ||
260 | ------------ | |
261 | % git config --get core.filemode | |
262 | ------------ | |
263 | ||
264 | or | |
265 | ||
266 | ------------ | |
267 | % git config core.filemode | |
268 | ------------ | |
269 | ||
270 | or, to query a multivar: | |
271 | ||
272 | ------------ | |
273 | % git config --get core.gitproxy "for kernel.org$" | |
274 | ------------ | |
275 | ||
276 | If you want to know all the values for a multivar, do: | |
277 | ||
278 | ------------ | |
279 | % git config --get-all core.gitproxy | |
280 | ------------ | |
281 | ||
544ddb04 | 282 | If you like to live dangerously, you can replace *all* core.gitproxy by a |
e0d10e1c TP |
283 | new one with |
284 | ||
285 | ------------ | |
286 | % git config --replace-all core.gitproxy ssh | |
287 | ------------ | |
288 | ||
289 | However, if you really only want to replace the line for the default proxy, | |
290 | i.e. the one without a "for ..." postfix, do something like this: | |
291 | ||
292 | ------------ | |
293 | % git config core.gitproxy ssh '! for ' | |
294 | ------------ | |
295 | ||
296 | To actually match only values with an exclamation mark, you have to | |
297 | ||
298 | ------------ | |
299 | % git config section.key value '[!]' | |
300 | ------------ | |
301 | ||
302 | To add a new proxy, without altering any of the existing ones, use | |
303 | ||
304 | ------------ | |
29093c28 | 305 | % git config core.gitproxy '"proxy-command" for example.com' |
e0d10e1c TP |
306 | ------------ |
307 | ||
9ce03522 JH |
308 | An example to use customized color from the configuration in your |
309 | script: | |
310 | ||
311 | ------------ | |
312 | #!/bin/sh | |
313 | WS=$(git config --get-color color.diff.whitespace "blue reverse") | |
314 | RESET=$(git config --get-color "" "reset") | |
315 | echo "${WS}your whitespace color or blue reverse${RESET}" | |
316 | ------------ | |
e0d10e1c TP |
317 | |
318 | include::config.txt[] | |
319 | ||
320 | ||
321 | Author | |
322 | ------ | |
323 | Written by Johannes Schindelin <Johannes.Schindelin@gmx.de> | |
324 | ||
325 | Documentation | |
326 | -------------- | |
327 | Documentation by Johannes Schindelin, Petr Baudis and the git-list <git@vger.kernel.org>. | |
328 | ||
329 | GIT | |
330 | --- | |
9e1f0a85 | 331 | Part of the linkgit:git[1] suite |