Raw
1 CONFIGURATION FILE
2 ------------------
3
4 The Git configuration file contains a number of variables that affect
5 the Git commands' behavior. The files `.git/config` and optionally
6 `config.worktree` (see the "CONFIGURATION FILE" section of
7 linkgit:git-worktree[1]) in each repository are used to store the
8 configuration for that repository, and `$HOME/.gitconfig` is used to
9 store a per-user configuration as fallback values for the `.git/config`
10 file. The file `/etc/gitconfig` can be used to store a system-wide
11 default configuration.
12
13 The configuration variables are used by both the Git plumbing
14 and the porcelain commands. The variables are divided into sections, wherein
15 the fully qualified variable name of the variable itself is the last
16 dot-separated segment and the section name is everything before the last
17 dot. The variable names are case-insensitive, allow only alphanumeric
18 characters and `-`, and must start with an alphabetic character. Some
19 variables may appear multiple times; we say then that the variable is
20 multivalued.
21
22 Syntax
23 ~~~~~~
24
25 The syntax is fairly flexible and permissive. Whitespace characters,
26 which in this context are the space character (SP) and the horizontal
27 tabulation (HT), are mostly ignored. The '#' and ';' characters begin
28 comments to the end of line. Blank lines are ignored.
29
30 The file consists of sections and variables. A section begins with
31 the name of the section in square brackets and continues until the next
32 section begins. Section names are case-insensitive. Only alphanumeric
33 characters, `-` and `.` are allowed in section names. Each variable
34 must belong to some section, which means that there must be a section
35 header before the first setting of a variable.
36
37 Sections can be further divided into subsections. To begin a subsection
38 put its name in double quotes, separated by space from the section name,
39 in the section header, like in the example below:
40
41 --------
42 [section "subsection"]
43
44 --------
45
46 Subsection names are case sensitive and can contain any characters except
47 newline and the null byte. Doublequote `"` and backslash can be included
48 by escaping them as `\"` and `\\`, respectively. Backslashes preceding
49 other characters are dropped when reading; for example, `\t` is read as
50 `t` and `\0` is read as `0`. Section headers cannot span multiple lines.
51 Variables may belong directly to a section or to a given subsection. You
52 can have `[section]` if you have `[section "subsection"]`, but you don't
53 need to.
54
55 There is also a deprecated `[section.subsection]` syntax. With this
56 syntax, the subsection name is converted to lower-case and is also
57 compared case sensitively. These subsection names follow the same
58 restrictions as section names.
59
60 All the other lines (and the remainder of the line after the section
61 header) are recognized as setting variables, in the form
62 'name = value' (or just 'name', which is a short-hand to say that
63 the variable is the boolean "true").
64 The variable names are case-insensitive, allow only alphanumeric characters
65 and `-`, and must start with an alphabetic character.
66
67 Whitespace characters surrounding `name`, `=` and `value` are discarded.
68 Internal whitespace characters within 'value' are retained verbatim.
69 Comments starting with either `#` or `;` and extending to the end of line
70 are discarded. A line that defines a value can be continued to the next
71 line by ending it with a backslash (`\`); the backslash and the end-of-line
72 characters are discarded.
73
74 If `value` needs to contain leading or trailing whitespace characters,
75 it must be enclosed in double quotation marks (`"`). Inside double quotation
76 marks, double quote (`"`) and backslash (`\`) characters must be escaped:
77 use `\"` for `"` and `\\` for `\`.
78
79 The following escape sequences (beside `\"` and `\\`) are recognized:
80 `\n` for newline character (NL), `\t` for horizontal tabulation (HT, TAB)
81 and `\b` for backspace (BS). Other char escape sequences (including octal
82 escape sequences) are invalid.
83
84
85 Includes
86 ~~~~~~~~
87
88 The `include` and `includeIf` sections allow you to include config
89 directives from another source. These sections behave identically to
90 each other with the exception that `includeIf` sections may be ignored
91 if their condition does not evaluate to true; see "Conditional includes"
92 below.
93
94 You can include a config file from another by setting the special
95 `include.path` (or `includeIf.*.path`) variable to the name of the file
96 to be included. The variable takes a pathname as its value, and is
97 subject to tilde expansion. These variables can be given multiple times.
98
99 The contents of the included file are inserted immediately, as if they
100 had been found at the location of the include directive. If the value of the
101 variable is a relative path, the path is considered to
102 be relative to the configuration file in which the include directive
103 was found. See below for examples.
104
105 Conditional includes
106 ~~~~~~~~~~~~~~~~~~~~
107
108 You can conditionally include a config file from another by setting an
109 `includeIf.<condition>.path` variable to the name of the file to be
110 included.
111
112 The condition starts with a keyword followed by a colon and some data
113 whose format and meaning depends on the keyword. Supported keywords
114 are:
115
116 `gitdir`::
117 The data that follows the keyword `gitdir` and a colon is used as a glob
118 pattern. If the location of the .git directory matches the
119 pattern, the include condition is met.
120 +
121 The .git location may be auto-discovered, or come from `$GIT_DIR`
122 environment variable. If the repository is auto-discovered via a .git
123 file (e.g. from submodules, or a linked worktree), the .git location
124 would be the final location where the .git directory is, not where the
125 .git file is.
126 +
127 The pattern can contain standard globbing wildcards and two additional
128 ones, `**/` and `/**`, that can match multiple path components. Please
129 refer to linkgit:gitignore[5] for details. For convenience:
130
131 * If the pattern starts with `~/`, `~` will be substituted with the
132 content of the environment variable `HOME`.
133
134 * If the pattern starts with `./`, it is replaced with the directory
135 containing the current config file.
136
137 * If the pattern does not start with either `~/`, `./` or `/`, `**/`
138 will be automatically prepended. For example, the pattern `foo/bar`
139 becomes `**/foo/bar` and would match `/any/path/to/foo/bar`.
140
141 * If the pattern ends with `/`, `**` will be automatically added. For
142 example, the pattern `foo/` becomes `foo/**`. In other words, it
143 matches "foo" and everything inside, recursively.
144
145 `gitdir/i`::
146 This is the same as `gitdir` except that matching is done
147 case-insensitively (e.g. on case-insensitive file systems)
148
149 `onbranch`::
150 The data that follows the keyword `onbranch` and a colon is taken to be a
151 pattern with standard globbing wildcards and two additional
152 ones, `**/` and `/**`, that can match multiple path components.
153 If we are in a worktree where the name of the branch that is
154 currently checked out matches the pattern, the include condition
155 is met.
156 +
157 If the pattern ends with `/`, `**` will be automatically added. For
158 example, the pattern `foo/` becomes `foo/**`. In other words, it matches
159 all branches that begin with `foo/`. This is useful if your branches are
160 organized hierarchically and you would like to apply a configuration to
161 all the branches in that hierarchy.
162
163 `hasconfig:remote.*.url`::
164 The data that follows this keyword and a colon is taken to
165 be a pattern with standard globbing wildcards and two
166 additional ones, `**/` and `/**`, that can match multiple
167 components. The first time this keyword is seen, the rest of
168 the config files will be scanned for remote URLs (without
169 applying any values). If there exists at least one remote URL
170 that matches this pattern, the include condition is met.
171 +
172 Files included by this option (directly or indirectly) are not allowed
173 to contain remote URLs.
174 +
175 Note that unlike other includeIf conditions, resolving this condition
176 relies on information that is not yet known at the point of reading the
177 condition. A typical use case is this option being present as a
178 system-level or global-level config, and the remote URL being in a
179 local-level config; hence the need to scan ahead when resolving this
180 condition. In order to avoid the chicken-and-egg problem in which
181 potentially-included files can affect whether such files are potentially
182 included, Git breaks the cycle by prohibiting these files from affecting
183 the resolution of these conditions (thus, prohibiting them from
184 declaring remote URLs).
185 +
186 As for the naming of this keyword, it is for forwards compatibility with
187 a naming scheme that supports more variable-based include conditions,
188 but currently Git only supports the exact keyword described above.
189
190 A few more notes on matching via `gitdir` and `gitdir/i`:
191
192 * Symlinks in `$GIT_DIR` are not resolved before matching.
193
194 * Both the symlink & realpath versions of paths will be matched
195 outside of `$GIT_DIR`. E.g. if ~/git is a symlink to
196 /mnt/storage/git, both `gitdir:~/git` and `gitdir:/mnt/storage/git`
197 will match.
198 +
199 This was not the case in the initial release of this feature in
200 v2.13.0, which only matched the realpath version. Configuration that
201 wants to be compatible with the initial release of this feature needs
202 to either specify only the realpath version, or both versions.
203
204 * Note that "../" is not special and will match literally, which is
205 unlikely what you want.
206
207 Example
208 ~~~~~~~
209
210 ----
211 # Core variables
212 [core]
213 ; Don't trust file modes
214 filemode = false
215
216 # Our diff algorithm
217 [diff]
218 external = /usr/local/bin/diff-wrapper
219 renames = true
220
221 [branch "devel"]
222 remote = origin
223 merge = refs/heads/devel
224
225 # Proxy settings
226 [core]
227 gitProxy="ssh" for "kernel.org"
228 gitProxy=default-proxy ; for the rest
229
230 [include]
231 path = /path/to/foo.inc ; include by absolute path
232 path = foo.inc ; find "foo.inc" relative to the current file
233 path = ~/foo.inc ; find "foo.inc" in your `$HOME` directory
234
235 ; include if $GIT_DIR is /path/to/foo/.git
236 [includeIf "gitdir:/path/to/foo/.git"]
237 path = /path/to/foo.inc
238
239 ; include for all repositories inside /path/to/group
240 [includeIf "gitdir:/path/to/group/"]
241 path = /path/to/foo.inc
242
243 ; include for all repositories inside $HOME/to/group
244 [includeIf "gitdir:~/to/group/"]
245 path = /path/to/foo.inc
246
247 ; relative paths are always relative to the including
248 ; file (if the condition is true); their location is not
249 ; affected by the condition
250 [includeIf "gitdir:/path/to/group/"]
251 path = foo.inc
252
253 ; include only if we are in a worktree where foo-branch is
254 ; currently checked out
255 [includeIf "onbranch:foo-branch"]
256 path = foo.inc
257
258 ; include only if a remote with the given URL exists (note
259 ; that such a URL may be provided later in a file or in a
260 ; file read after this file is read, as seen in this example)
261 [includeIf "hasconfig:remote.*.url:https://example.com/**"]
262 path = foo.inc
263 [remote "origin"]
264 url = https://example.com/git
265 ----
266
267 Values
268 ~~~~~~
269
270 Values of many variables are treated as a simple string, but there
271 are variables that take values of specific types and there are rules
272 as to how to spell them.
273
274 boolean::
275
276 When a variable is said to take a boolean value, many
277 synonyms are accepted for 'true' and 'false'; these are all
278 case-insensitive.
279 +
280 --
281 true;; Boolean true literals are `yes`, `on`, `true`,
282 and `1`. Also, a variable defined without `= <value>`
283 is taken as true.
284
285 false;; Boolean false literals are `no`, `off`, `false`,
286 `0` and the empty string.
287 --
288 +
289 When converting a value to its canonical form using the `--type=bool` type
290 specifier, 'git config' will ensure that the output is "true" or
291 "false" (spelled in lowercase).
292
293 integer::
294 The value for many variables that specify various sizes can
295 be suffixed with `k`, `M`,... to mean "scale the number by
296 1024", "by 1024x1024", etc.
297
298 color::
299 The value for a variable that takes a color is a list of
300 colors (at most two, one for foreground and one for background)
301 and attributes (as many as you want), separated by spaces.
302 +
303 The basic colors accepted are `normal`, `black`, `red`, `green`,
304 `yellow`, `blue`, `magenta`, `cyan`, `white` and `default`. The first
305 color given is the foreground; the second is the background. All the
306 basic colors except `normal` and `default` have a bright variant that can
307 be specified by prefixing the color with `bright`, like `brightred`.
308 +
309 The color `normal` makes no change to the color. It is the same as an
310 empty string, but can be used as the foreground color when specifying a
311 background color alone (for example, "normal red").
312 +
313 The color `default` explicitly resets the color to the terminal default,
314 for example to specify a cleared background. Although it varies between
315 terminals, this is usually not the same as setting to "white black".
316 +
317 Colors may also be given as numbers between 0 and 255; these use ANSI
318 256-color mode (but note that not all terminals may support this). If
319 your terminal supports it, you may also specify 24-bit RGB values as
320 hex, like `#ff0ab3`, or 12-bit RGB values like `#f1b`, which is
321 equivalent to the 24-bit color `#ff11bb`.
322 +
323 The accepted attributes are `bold`, `dim`, `ul`, `blink`, `reverse`,
324 `italic`, and `strike` (for crossed-out or "strikethrough" letters).
325 The position of any attributes with respect to the colors
326 (before, after, or in between), doesn't matter. Specific attributes may
327 be turned off by prefixing them with `no` or `no-` (e.g., `noreverse`,
328 `no-ul`, etc).
329 +
330 The pseudo-attribute `reset` resets all colors and attributes before
331 applying the specified coloring. For example, `reset green` will result
332 in a green foreground and default background without any active
333 attributes.
334 +
335 An empty color string produces no color effect at all. This can be used
336 to avoid coloring specific elements without disabling color entirely.
337 +
338 For git's pre-defined color slots, the attributes are meant to be reset
339 at the beginning of each item in the colored output. So setting
340 `color.decorate.branch` to `black` will paint that branch name in a
341 plain `black`, even if the previous thing on the same output line (e.g.
342 opening parenthesis before the list of branch names in `log --decorate`
343 output) is set to be painted with `bold` or some other attribute.
344 However, custom log formats may do more complicated and layered
345 coloring, and the negated forms may be useful there.
346
347 pathname::
348 A variable that takes a pathname value can be given a
349 string that begins with "`~/`" or "`~user/`", and the usual
350 tilde expansion happens to such a string: `~/`
351 is expanded to the value of `$HOME`, and `~user/` to the
352 specified user's home directory.
353 +
354 If a path starts with `%(prefix)/`, the remainder is interpreted as a
355 path relative to Git's "runtime prefix", i.e. relative to the location
356 where Git itself was installed. For example, `%(prefix)/bin/` refers to
357 the directory in which the Git executable itself lives. If Git was
358 compiled without runtime prefix support, the compiled-in prefix will be
359 substituted instead. In the unlikely event that a literal path needs to
360 be specified that should _not_ be expanded, it needs to be prefixed by
361 `./`, like so: `./%(prefix)/bin`.
362 +
363 If prefixed with `:(optional)`, the configuration variable is treated
364 as if it does not exist, if the named path does not exist.
365
366 Variables
367 ~~~~~~~~~
368
369 Note that this list is non-comprehensive and not necessarily complete.
370 For command-specific variables, you will find a more detailed description
371 in the appropriate manual page.
372
373 Other git-related tools may and do use their own variables. When
374 inventing new variables for use in your own tool, make sure their
375 names do not conflict with those that are used by Git itself and
376 other popular tools, and describe them in your documentation.
377
378 include::config/add.adoc[]
379
380 include::config/advice.adoc[]
381
382 include::config/alias.adoc[]
383
384 include::config/am.adoc[]
385
386 include::config/apply.adoc[]
387
388 include::config/attr.adoc[]
389
390 include::config/bitmap-pseudo-merge.adoc[]
391
392 include::config/blame.adoc[]
393
394 include::config/branch.adoc[]
395
396 include::config/browser.adoc[]
397
398 include::config/bundle.adoc[]
399
400 include::config/checkout.adoc[]
401
402 include::config/clean.adoc[]
403
404 include::config/clone.adoc[]
405
406 include::config/color.adoc[]
407
408 include::config/column.adoc[]
409
410 include::config/commit.adoc[]
411
412 include::config/commitgraph.adoc[]
413
414 include::config/completion.adoc[]
415
416 include::config/core.adoc[]
417
418 include::config/credential.adoc[]
419
420 include::config/diff.adoc[]
421
422 include::config/difftool.adoc[]
423
424 include::config/extensions.adoc[]
425
426 include::config/fastimport.adoc[]
427
428 include::config/feature.adoc[]
429
430 include::config/fetch.adoc[]
431
432 include::config/filter.adoc[]
433
434 include::config/format.adoc[]
435
436 include::config/fsck.adoc[]
437
438 include::config/fsmonitor--daemon.adoc[]
439
440 include::config/gc.adoc[]
441
442 include::config/gitcvs.adoc[]
443
444 include::config/gitweb.adoc[]
445
446 include::config/gpg.adoc[]
447
448 include::config/grep.adoc[]
449
450 include::config/gui.adoc[]
451
452 include::config/guitool.adoc[]
453
454 include::config/help.adoc[]
455
456 include::config/hook.adoc[]
457
458 include::config/http.adoc[]
459
460 include::config/i18n.adoc[]
461
462 include::config/imap.adoc[]
463
464 include::config/includeif.adoc[]
465
466 include::config/index.adoc[]
467
468 include::config/init.adoc[]
469
470 include::config/instaweb.adoc[]
471
472 include::config/interactive.adoc[]
473
474 include::config/log.adoc[]
475
476 include::config/lsrefs.adoc[]
477
478 include::config/mailinfo.adoc[]
479
480 include::config/mailmap.adoc[]
481
482 include::config/maintenance.adoc[]
483
484 include::config/man.adoc[]
485
486 include::config/merge.adoc[]
487
488 include::config/mergetool.adoc[]
489
490 include::config/notes.adoc[]
491
492 include::config/pack.adoc[]
493
494 include::config/pager.adoc[]
495
496 include::config/pretty.adoc[]
497
498 include::config/promisor.adoc[]
499
500 include::config/protocol.adoc[]
501
502 include::config/pull.adoc[]
503
504 include::config/push.adoc[]
505
506 include::config/rebase.adoc[]
507
508 include::config/receive.adoc[]
509
510 include::config/reftable.adoc[]
511
512 include::config/remote.adoc[]
513
514 include::config/remotes.adoc[]
515
516 include::config/repack.adoc[]
517
518 include::config/rerere.adoc[]
519
520 include::config/revert.adoc[]
521
522 include::config/safe.adoc[]
523
524 include::config/sendemail.adoc[]
525
526 include::config/sequencer.adoc[]
527
528 include::config/showbranch.adoc[]
529
530 include::config/sideband.adoc[]
531
532 include::config/sparse.adoc[]
533
534 include::config/splitindex.adoc[]
535
536 include::config/ssh.adoc[]
537
538 include::config/stash.adoc[]
539
540 include::config/status.adoc[]
541
542 include::config/submodule.adoc[]
543
544 include::config/tag.adoc[]
545
546 include::config/tar.adoc[]
547
548 include::config/trace2.adoc[]
549
550 include::config/trailer.adoc[]
551
552 include::config/transfer.adoc[]
553
554 include::config/uploadarchive.adoc[]
555
556 include::config/uploadpack.adoc[]
557
558 include::config/url.adoc[]
559
560 include::config/user.adoc[]
561
562 include::config/versionsort.adoc[]
563
564 include::config/web.adoc[]
565
566 include::config/worktree.adoc[]