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