]> git.ipfire.org Git - thirdparty/git.git/blob - Documentation/config.txt
Merge branch 'jk/HEAD-symref-in-xfer-namespaces'
[thirdparty/git.git] / Documentation / config.txt
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 `extensions.worktreeConfig` below) in each
7 repository are used to store the configuration for that repository, and
8 `$HOME/.gitconfig` is used to store a per-user configuration as
9 fallback values for the `.git/config` file. The file `/etc/gitconfig`
10 can be used to store a system-wide default configuration.
11
12 The configuration variables are used by both the Git plumbing
13 and the porcelains. The variables are divided into sections, wherein
14 the fully qualified variable name of the variable itself is the last
15 dot-separated segment and the section name is everything before the last
16 dot. The variable names are case-insensitive, allow only alphanumeric
17 characters and `-`, and must start with an alphabetic character. Some
18 variables may appear multiple times; we say then that the variable is
19 multivalued.
20
21 Syntax
22 ~~~~~~
23
24 The syntax is fairly flexible and permissive; whitespaces are mostly
25 ignored. The '#' and ';' characters begin comments to the end of line,
26 blank lines are ignored.
27
28 The file consists of sections and variables. A section begins with
29 the name of the section in square brackets and continues until the next
30 section begins. Section names are case-insensitive. Only alphanumeric
31 characters, `-` and `.` are allowed in section names. Each variable
32 must belong to some section, which means that there must be a section
33 header before the first setting of a variable.
34
35 Sections can be further divided into subsections. To begin a subsection
36 put its name in double quotes, separated by space from the section name,
37 in the section header, like in the example below:
38
39 --------
40 [section "subsection"]
41
42 --------
43
44 Subsection names are case sensitive and can contain any characters except
45 newline and the null byte. Doublequote `"` and backslash can be included
46 by escaping them as `\"` and `\\`, respectively. Backslashes preceding
47 other characters are dropped when reading; for example, `\t` is read as
48 `t` and `\0` is read as `0` Section headers cannot span multiple lines.
49 Variables may belong directly to a section or to a given subsection. You
50 can have `[section]` if you have `[section "subsection"]`, but you don't
51 need to.
52
53 There is also a deprecated `[section.subsection]` syntax. With this
54 syntax, the subsection name is converted to lower-case and is also
55 compared case sensitively. These subsection names follow the same
56 restrictions as section names.
57
58 All the other lines (and the remainder of the line after the section
59 header) are recognized as setting variables, in the form
60 'name = value' (or just 'name', which is a short-hand to say that
61 the variable is the boolean "true").
62 The variable names are case-insensitive, allow only alphanumeric characters
63 and `-`, and must start with an alphabetic character.
64
65 A line that defines a value can be continued to the next line by
66 ending it with a `\`; the backquote and the end-of-line are
67 stripped. Leading whitespaces after 'name =', the remainder of the
68 line after the first comment character '#' or ';', and trailing
69 whitespaces of the line are discarded unless they are enclosed in
70 double quotes. Internal whitespaces within the value are retained
71 verbatim.
72
73 Inside double quotes, double quote `"` and backslash `\` characters
74 must be escaped: use `\"` for `"` and `\\` for `\`.
75
76 The following escape sequences (beside `\"` and `\\`) are recognized:
77 `\n` for newline character (NL), `\t` for horizontal tabulation (HT, TAB)
78 and `\b` for backspace (BS). Other char escape sequences (including octal
79 escape sequences) are invalid.
80
81
82 Includes
83 ~~~~~~~~
84
85 The `include` and `includeIf` sections allow you to include config
86 directives from another source. These sections behave identically to
87 each other with the exception that `includeIf` sections may be ignored
88 if their condition does not evaluate to true; see "Conditional includes"
89 below.
90
91 You can include a config file from another by setting the special
92 `include.path` (or `includeIf.*.path`) variable to the name of the file
93 to be included. The variable takes a pathname as its value, and is
94 subject to tilde expansion. These variables can be given multiple times.
95
96 The contents of the included file are inserted immediately, as if they
97 had been found at the location of the include directive. If the value of the
98 variable is a relative path, the path is considered to
99 be relative to the configuration file in which the include directive
100 was found. See below for examples.
101
102 Conditional includes
103 ~~~~~~~~~~~~~~~~~~~~
104
105 You can include a config file from another conditionally by setting a
106 `includeIf.<condition>.path` variable to the name of the file to be
107 included.
108
109 The condition starts with a keyword followed by a colon and some data
110 whose format and meaning depends on the keyword. Supported keywords
111 are:
112
113 `gitdir`::
114
115 The data that follows the keyword `gitdir:` is used as a glob
116 pattern. If the location of the .git directory matches the
117 pattern, the include condition is met.
118 +
119 The .git location may be auto-discovered, or come from `$GIT_DIR`
120 environment variable. If the repository is auto discovered via a .git
121 file (e.g. from submodules, or a linked worktree), the .git location
122 would be the final location where the .git directory is, not where the
123 .git file is.
124 +
125 The pattern can contain standard globbing wildcards and two additional
126 ones, `**/` and `/**`, that can match multiple path components. Please
127 refer to linkgit:gitignore[5] for details. For convenience:
128
129 * If the pattern starts with `~/`, `~` will be substituted with the
130 content of the environment variable `HOME`.
131
132 * If the pattern starts with `./`, it is replaced with the directory
133 containing the current config file.
134
135 * If the pattern does not start with either `~/`, `./` or `/`, `**/`
136 will be automatically prepended. For example, the pattern `foo/bar`
137 becomes `**/foo/bar` and would match `/any/path/to/foo/bar`.
138
139 * If the pattern ends with `/`, `**` will be automatically added. For
140 example, the pattern `foo/` becomes `foo/**`. In other words, it
141 matches "foo" and everything inside, recursively.
142
143 `gitdir/i`::
144 This is the same as `gitdir` except that matching is done
145 case-insensitively (e.g. on case-insensitive file sytems)
146
147 A few more notes on matching via `gitdir` and `gitdir/i`:
148
149 * Symlinks in `$GIT_DIR` are not resolved before matching.
150
151 * Both the symlink & realpath versions of paths will be matched
152 outside of `$GIT_DIR`. E.g. if ~/git is a symlink to
153 /mnt/storage/git, both `gitdir:~/git` and `gitdir:/mnt/storage/git`
154 will match.
155 +
156 This was not the case in the initial release of this feature in
157 v2.13.0, which only matched the realpath version. Configuration that
158 wants to be compatible with the initial release of this feature needs
159 to either specify only the realpath version, or both versions.
160
161 * Note that "../" is not special and will match literally, which is
162 unlikely what you want.
163
164 Example
165 ~~~~~~~
166
167 # Core variables
168 [core]
169 ; Don't trust file modes
170 filemode = false
171
172 # Our diff algorithm
173 [diff]
174 external = /usr/local/bin/diff-wrapper
175 renames = true
176
177 [branch "devel"]
178 remote = origin
179 merge = refs/heads/devel
180
181 # Proxy settings
182 [core]
183 gitProxy="ssh" for "kernel.org"
184 gitProxy=default-proxy ; for the rest
185
186 [include]
187 path = /path/to/foo.inc ; include by absolute path
188 path = foo.inc ; find "foo.inc" relative to the current file
189 path = ~/foo.inc ; find "foo.inc" in your `$HOME` directory
190
191 ; include if $GIT_DIR is /path/to/foo/.git
192 [includeIf "gitdir:/path/to/foo/.git"]
193 path = /path/to/foo.inc
194
195 ; include for all repositories inside /path/to/group
196 [includeIf "gitdir:/path/to/group/"]
197 path = /path/to/foo.inc
198
199 ; include for all repositories inside $HOME/to/group
200 [includeIf "gitdir:~/to/group/"]
201 path = /path/to/foo.inc
202
203 ; relative paths are always relative to the including
204 ; file (if the condition is true); their location is not
205 ; affected by the condition
206 [includeIf "gitdir:/path/to/group/"]
207 path = foo.inc
208
209 Values
210 ~~~~~~
211
212 Values of many variables are treated as a simple string, but there
213 are variables that take values of specific types and there are rules
214 as to how to spell them.
215
216 boolean::
217
218 When a variable is said to take a boolean value, many
219 synonyms are accepted for 'true' and 'false'; these are all
220 case-insensitive.
221
222 true;; Boolean true literals are `yes`, `on`, `true`,
223 and `1`. Also, a variable defined without `= <value>`
224 is taken as true.
225
226 false;; Boolean false literals are `no`, `off`, `false`,
227 `0` and the empty string.
228 +
229 When converting a value to its canonical form using the `--type=bool` type
230 specifier, 'git config' will ensure that the output is "true" or
231 "false" (spelled in lowercase).
232
233 integer::
234 The value for many variables that specify various sizes can
235 be suffixed with `k`, `M`,... to mean "scale the number by
236 1024", "by 1024x1024", etc.
237
238 color::
239 The value for a variable that takes a color is a list of
240 colors (at most two, one for foreground and one for background)
241 and attributes (as many as you want), separated by spaces.
242 +
243 The basic colors accepted are `normal`, `black`, `red`, `green`, `yellow`,
244 `blue`, `magenta`, `cyan` and `white`. The first color given is the
245 foreground; the second is the background.
246 +
247 Colors may also be given as numbers between 0 and 255; these use ANSI
248 256-color mode (but note that not all terminals may support this). If
249 your terminal supports it, you may also specify 24-bit RGB values as
250 hex, like `#ff0ab3`.
251 +
252 The accepted attributes are `bold`, `dim`, `ul`, `blink`, `reverse`,
253 `italic`, and `strike` (for crossed-out or "strikethrough" letters).
254 The position of any attributes with respect to the colors
255 (before, after, or in between), doesn't matter. Specific attributes may
256 be turned off by prefixing them with `no` or `no-` (e.g., `noreverse`,
257 `no-ul`, etc).
258 +
259 An empty color string produces no color effect at all. This can be used
260 to avoid coloring specific elements without disabling color entirely.
261 +
262 For git's pre-defined color slots, the attributes are meant to be reset
263 at the beginning of each item in the colored output. So setting
264 `color.decorate.branch` to `black` will paint that branch name in a
265 plain `black`, even if the previous thing on the same output line (e.g.
266 opening parenthesis before the list of branch names in `log --decorate`
267 output) is set to be painted with `bold` or some other attribute.
268 However, custom log formats may do more complicated and layered
269 coloring, and the negated forms may be useful there.
270
271 pathname::
272 A variable that takes a pathname value can be given a
273 string that begins with "`~/`" or "`~user/`", and the usual
274 tilde expansion happens to such a string: `~/`
275 is expanded to the value of `$HOME`, and `~user/` to the
276 specified user's home directory.
277
278
279 Variables
280 ~~~~~~~~~
281
282 Note that this list is non-comprehensive and not necessarily complete.
283 For command-specific variables, you will find a more detailed description
284 in the appropriate manual page.
285
286 Other git-related tools may and do use their own variables. When
287 inventing new variables for use in your own tool, make sure their
288 names do not conflict with those that are used by Git itself and
289 other popular tools, and describe them in your documentation.
290
291 include::config/advice.txt[]
292
293 include::config/core.txt[]
294
295 include::config/add.txt[]
296
297 include::config/alias.txt[]
298
299 include::config/am.txt[]
300
301 include::config/apply.txt[]
302
303 include::config/blame.txt[]
304
305 include::config/branch.txt[]
306
307 include::config/browser.txt[]
308
309 include::config/checkout.txt[]
310
311 include::config/clean.txt[]
312
313 include::config/color.txt[]
314
315 include::config/column.txt[]
316
317 include::config/commit.txt[]
318
319 include::config/credential.txt[]
320
321 include::config/completion.txt[]
322
323 include::config/diff.txt[]
324
325 include::config/difftool.txt[]
326
327 include::config/fastimport.txt[]
328
329 include::config/fetch.txt[]
330
331 include::config/format.txt[]
332
333 include::config/filter.txt[]
334
335 include::config/fsck.txt[]
336
337 include::config/gc.txt[]
338
339 include::config/gitcvs.txt[]
340
341 include::config/gitweb.txt[]
342
343 include::config/grep.txt[]
344
345 include::config/gpg.txt[]
346
347 include::config/gui.txt[]
348
349 include::config/guitool.txt[]
350
351 include::config/help.txt[]
352
353 include::config/http.txt[]
354
355 include::config/i18n.txt[]
356
357 include::config/imap.txt[]
358
359 include::config/index.txt[]
360
361 include::config/init.txt[]
362
363 include::config/instaweb.txt[]
364
365 include::config/interactive.txt[]
366
367 include::config/log.txt[]
368
369 include::config/mailinfo.txt[]
370
371 include::config/mailmap.txt[]
372
373 include::config/man.txt[]
374
375 include::config/merge.txt[]
376
377 include::config/mergetool.txt[]
378
379 include::config/notes.txt[]
380
381 include::config/pack.txt[]
382
383 include::config/pager.txt[]
384
385 include::config/pretty.txt[]
386
387 include::config/protocol.txt[]
388
389 include::config/pull.txt[]
390
391 include::config/push.txt[]
392
393 include::config/rebase.txt[]
394
395 include::config/receive.txt[]
396
397 include::config/remote.txt[]
398
399 include::config/remotes.txt[]
400
401 include::config/repack.txt[]
402
403 include::config/rerere.txt[]
404
405 include::config/reset.txt[]
406
407 include::config/sendemail.txt[]
408
409 include::config/sequencer.txt[]
410
411 include::config/showbranch.txt[]
412
413 include::config/splitindex.txt[]
414
415 include::config/ssh.txt[]
416
417 include::config/status.txt[]
418
419 include::config/stash.txt[]
420
421 include::config/submodule.txt[]
422
423 include::config/tag.txt[]
424
425 include::config/trace2.txt[]
426
427 include::config/transfer.txt[]
428
429 include::config/uploadarchive.txt[]
430
431 include::config/uploadpack.txt[]
432
433 include::config/url.txt[]
434
435 include::config/user.txt[]
436
437 include::config/versionsort.txt[]
438
439 include::config/web.txt[]
440
441 include::config/worktree.txt[]