repo-settings: create feature.manyFiles setting
[git/git.git] / Documentation / config.txt
CommitLineData
1ab661dd
PB
1CONFIGURATION FILE
2------------------
3
2de9b711 4The Git configuration file contains a number of variables that affect
58b284a2
NTND
5the Git commands' behavior. The files `.git/config` and optionally
6`config.worktree` (see `extensions.worktreeConfig` below) in each
7repository are used to store the configuration for that repository, and
66e35fcb 8`$HOME/.gitconfig` is used to store a per-user configuration as
773002a7 9fallback values for the `.git/config` file. The file `/etc/gitconfig`
66e35fcb 10can be used to store a system-wide default configuration.
5ea5621f 11
2de9b711 12The configuration variables are used by both the Git plumbing
b7ee2266
SB
13and the porcelains. The variables are divided into sections, wherein
14the fully qualified variable name of the variable itself is the last
1ab661dd 15dot-separated segment and the section name is everything before the last
e0a4aae8
LP
16dot. The variable names are case-insensitive, allow only alphanumeric
17characters and `-`, and must start with an alphabetic character. Some
a5285b6c
JH
18variables may appear multiple times; we say then that the variable is
19multivalued.
1ab661dd 20
e136f33b
JN
21Syntax
22~~~~~~
23
1ab661dd 24The syntax is fairly flexible and permissive; whitespaces are mostly
e136f33b
JN
25ignored. The '#' and ';' characters begin comments to the end of line,
26blank lines are ignored.
27
28The file consists of sections and variables. A section begins with
29the name of the section in square brackets and continues until the next
05c3e5c7 30section begins. Section names are case-insensitive. Only alphanumeric
dcb11263 31characters, `-` and `.` are allowed in section names. Each variable
773002a7
SB
32must belong to some section, which means that there must be a section
33header before the first setting of a variable.
e136f33b
JN
34
35Sections can be further divided into subsections. To begin a subsection
36put its name in double quotes, separated by space from the section name,
773002a7 37in the section header, like in the example below:
e136f33b
JN
38
39--------
40 [section "subsection"]
41
42--------
43
b7ee2266 44Subsection names are case sensitive and can contain any characters except
1feb0617
DB
45newline and the null byte. Doublequote `"` and backslash can be included
46by escaping them as `\"` and `\\`, respectively. Backslashes preceding
47other 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.
49Variables may belong directly to a section or to a given subsection. You
50can have `[section]` if you have `[section "subsection"]`, but you don't
51need to.
e136f33b 52
f7376329
CMN
53There is also a deprecated `[section.subsection]` syntax. With this
54syntax, the subsection name is converted to lower-case and is also
55compared case sensitively. These subsection names follow the same
56restrictions as section names.
e136f33b 57
2ceb639f
NS
58All the other lines (and the remainder of the line after the section
59header) are recognized as setting variables, in the form
1c448b3b
JH
60'name = value' (or just 'name', which is a short-hand to say that
61the variable is the boolean "true").
e0a4aae8 62The variable names are case-insensitive, allow only alphanumeric characters
a5285b6c 63and `-`, and must start with an alphabetic character.
e136f33b 64
ff5507ed
JH
65A line that defines a value can be continued to the next line by
66ending it with a `\`; the backquote and the end-of-line are
67stripped. Leading whitespaces after 'name =', the remainder of the
68line after the first comment character '#' or ';', and trailing
69whitespaces of the line are discarded unless they are enclosed in
70double quotes. Internal whitespaces within the value are retained
71verbatim.
e136f33b 72
ff5507ed
JH
73Inside double quotes, double quote `"` and backslash `\` characters
74must be escaped: use `\"` for `"` and `\\` for `\`.
e136f33b 75
dcb11263
CJ
76The following escape sequences (beside `\"` and `\\`) are recognized:
77`\n` for newline character (NL), `\t` for horizontal tabulation (HT, TAB)
a58088ab
JL
78and `\b` for backspace (BS). Other char escape sequences (including octal
79escape sequences) are invalid.
e136f33b 80
1ab661dd 81
9b25a0b5
JK
82Includes
83~~~~~~~~
84
9d71d94d
JK
85The `include` and `includeIf` sections allow you to include config
86directives from another source. These sections behave identically to
87each other with the exception that `includeIf` sections may be ignored
88if their condition does not evaluate to true; see "Conditional includes"
89below.
90
df0233be 91You can include a config file from another by setting the special
9d71d94d
JK
92`include.path` (or `includeIf.*.path`) variable to the name of the file
93to be included. The variable takes a pathname as its value, and is
94subject to tilde expansion. These variables can be given multiple times.
dca83abd 95
a076df28
JK
96The contents of the included file are inserted immediately, as if they
97had been found at the location of the include directive. If the value of the
9d71d94d 98variable is a relative path, the path is considered to
1050e987
NTND
99be relative to the configuration file in which the include directive
100was found. See below for examples.
dca83abd 101
3efd0bed
NTND
102Conditional includes
103~~~~~~~~~~~~~~~~~~~~
104
105You can include a config file from another conditionally by setting a
106`includeIf.<condition>.path` variable to the name of the file to be
9d71d94d 107included.
3efd0bed
NTND
108
109The condition starts with a keyword followed by a colon and some data
110whose format and meaning depends on the keyword. Supported keywords
111are:
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+
119The .git location may be auto-discovered, or come from `$GIT_DIR`
120environment variable. If the repository is auto discovered via a .git
121file (e.g. from submodules, or a linked worktree), the .git location
122would be the final location where the .git directory is, not where the
123.git file is.
124+
125The pattern can contain standard globbing wildcards and two additional
126ones, `**/` and `/**`, that can match multiple path components. Please
127refer 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
07b2c0ea
DL
147`onbranch`::
148 The data that follows the keyword `onbranch:` is taken to be a
149 pattern with standard globbing wildcards and two additional
150 ones, `**/` and `/**`, that can match multiple path components.
151 If we are in a worktree where the name of the branch that is
152 currently checked out matches the pattern, the include condition
153 is met.
154+
155If the pattern ends with `/`, `**` will be automatically added. For
156example, the pattern `foo/` becomes `foo/**`. In other words, it matches
157all branches that begin with `foo/`. This is useful if your branches are
158organized hierarchically and you would like to apply a configuration to
159all the branches in that hierarchy.
160
3efd0bed
NTND
161A few more notes on matching via `gitdir` and `gitdir/i`:
162
163 * Symlinks in `$GIT_DIR` are not resolved before matching.
164
0624c63c
ÆAB
165 * Both the symlink & realpath versions of paths will be matched
166 outside of `$GIT_DIR`. E.g. if ~/git is a symlink to
167 /mnt/storage/git, both `gitdir:~/git` and `gitdir:/mnt/storage/git`
168 will match.
169+
170This was not the case in the initial release of this feature in
171v2.13.0, which only matched the realpath version. Configuration that
172wants to be compatible with the initial release of this feature needs
173to either specify only the realpath version, or both versions.
174
3efd0bed
NTND
175 * Note that "../" is not special and will match literally, which is
176 unlikely what you want.
9b25a0b5 177
1ab661dd
PB
178Example
179~~~~~~~
180
181 # Core variables
182 [core]
183 ; Don't trust file modes
184 filemode = false
185
186 # Our diff algorithm
187 [diff]
6bb9e51b 188 external = /usr/local/bin/diff-wrapper
1ab661dd
PB
189 renames = true
190
910c00c8
AK
191 [branch "devel"]
192 remote = origin
193 merge = refs/heads/devel
194
e136f33b
JN
195 # Proxy settings
196 [core]
29093c28 197 gitProxy="ssh" for "kernel.org"
e136f33b 198 gitProxy=default-proxy ; for the rest
910c00c8 199
9b25a0b5
JK
200 [include]
201 path = /path/to/foo.inc ; include by absolute path
ce933ebd
JK
202 path = foo.inc ; find "foo.inc" relative to the current file
203 path = ~/foo.inc ; find "foo.inc" in your `$HOME` directory
9b25a0b5 204
3efd0bed
NTND
205 ; include if $GIT_DIR is /path/to/foo/.git
206 [includeIf "gitdir:/path/to/foo/.git"]
207 path = /path/to/foo.inc
208
209 ; include for all repositories inside /path/to/group
210 [includeIf "gitdir:/path/to/group/"]
211 path = /path/to/foo.inc
212
213 ; include for all repositories inside $HOME/to/group
214 [includeIf "gitdir:~/to/group/"]
215 path = /path/to/foo.inc
5f7b91ba 216
994cd6c7
JK
217 ; relative paths are always relative to the including
218 ; file (if the condition is true); their location is not
219 ; affected by the condition
220 [includeIf "gitdir:/path/to/group/"]
221 path = foo.inc
222
07b2c0ea
DL
223 ; include only if we are in a worktree where foo-branch is
224 ; currently checked out
225 [includeIf "onbranch:foo-branch"]
226 path = foo.inc
227
5f7b91ba
JH
228Values
229~~~~~~
230
231Values of many variables are treated as a simple string, but there
232are variables that take values of specific types and there are rules
233as to how to spell them.
234
235boolean::
236
237 When a variable is said to take a boolean value, many
238 synonyms are accepted for 'true' and 'false'; these are all
239 case-insensitive.
240
7f0a02be
AH
241 true;; Boolean true literals are `yes`, `on`, `true`,
242 and `1`. Also, a variable defined without `= <value>`
5f7b91ba
JH
243 is taken as true.
244
7f0a02be
AH
245 false;; Boolean false literals are `no`, `off`, `false`,
246 `0` and the empty string.
5f7b91ba 247+
ed3bb3df 248When converting a value to its canonical form using the `--type=bool` type
7f0a02be 249specifier, 'git config' will ensure that the output is "true" or
5f7b91ba
JH
250"false" (spelled in lowercase).
251
252integer::
253 The value for many variables that specify various sizes can
254 be suffixed with `k`, `M`,... to mean "scale the number by
255 1024", "by 1024x1024", etc.
256
b92c1a28 257color::
adb33566
JK
258 The value for a variable that takes a color is a list of
259 colors (at most two, one for foreground and one for background)
260 and attributes (as many as you want), separated by spaces.
5f456b3c 261+
adb33566
JK
262The basic colors accepted are `normal`, `black`, `red`, `green`, `yellow`,
263`blue`, `magenta`, `cyan` and `white`. The first color given is the
264foreground; the second is the background.
5ee87585 265+
adb33566
JK
266Colors may also be given as numbers between 0 and 255; these use ANSI
267256-color mode (but note that not all terminals may support this). If
268your terminal supports it, you may also specify 24-bit RGB values as
269hex, like `#ff0ab3`.
270+
9dc3515c
JK
271The accepted attributes are `bold`, `dim`, `ul`, `blink`, `reverse`,
272`italic`, and `strike` (for crossed-out or "strikethrough" letters).
273The position of any attributes with respect to the colors
54590a0e
JK
274(before, after, or in between), doesn't matter. Specific attributes may
275be turned off by prefixing them with `no` or `no-` (e.g., `noreverse`,
276`no-ul`, etc).
adb33566 277+
512aba26
JK
278An empty color string produces no color effect at all. This can be used
279to avoid coloring specific elements without disabling color entirely.
280+
adb33566
JK
281For git's pre-defined color slots, the attributes are meant to be reset
282at the beginning of each item in the colored output. So setting
283`color.decorate.branch` to `black` will paint that branch name in a
284plain `black`, even if the previous thing on the same output line (e.g.
285opening parenthesis before the list of branch names in `log --decorate`
286output) is set to be painted with `bold` or some other attribute.
287However, custom log formats may do more complicated and layered
288coloring, and the negated forms may be useful there.
b92c1a28 289
dca83abd
JH
290pathname::
291 A variable that takes a pathname value can be given a
292 string that begins with "`~/`" or "`~user/`", and the usual
293 tilde expansion happens to such a string: `~/`
294 is expanded to the value of `$HOME`, and `~user/` to the
295 specified user's home directory.
296
5f7b91ba 297
1ab661dd
PB
298Variables
299~~~~~~~~~
300
301Note that this list is non-comprehensive and not necessarily complete.
b8936cf0 302For command-specific variables, you will find a more detailed description
93728b23
CA
303in the appropriate manual page.
304
305Other git-related tools may and do use their own variables. When
306inventing new variables for use in your own tool, make sure their
307names do not conflict with those that are used by Git itself and
308other popular tools, and describe them in your documentation.
309
838ef420 310include::config/advice.txt[]
75194438 311
1a394fa9 312include::config/core.txt[]
dce96489 313
29120d8e 314include::config/add.txt[]
13bd2134 315
f740c8f1 316include::config/alias.txt[]
dfd42a3c 317
d293ffef 318include::config/am.txt[]
e97a5e76 319
696d4796 320include::config/apply.txt[]
1ab661dd 321
d09467b6 322include::config/blame.txt[]
8578037b 323
7273b95d 324include::config/branch.txt[]
a5ba2cbe 325
6b0b9740 326include::config/browser.txt[]
584627b4 327
9140b410 328include::config/checkout.txt[]
fa655d84 329
328e629c 330include::config/clean.txt[]
2122591b 331
0a7839e3 332include::config/color.txt[]
6b2f2d98 333
dbfc949f 334include::config/column.txt[]
d96e3c15 335
5453d236 336include::config/commit.txt[]
aaab8420 337
3a49be6d 338include::config/credential.txt[]
7f4d4746 339
2b4b7305 340include::config/completion.txt[]
6532f374 341
fa922d74 342include::config/diff.txt[]
afcbc8e7 343
9155f6f6 344include::config/difftool.txt[]
a904392e 345
f2e58246 346include::config/fastimport.txt[]
d9545c7f 347
c6cc4c5a
DS
348include::config/feature.txt[]
349
561fda20 350include::config/fetch.txt[]
42cc7485 351
ab14f494 352include::config/format.txt[]
bb52995f 353
734dfebb 354include::config/filter.txt[]
26488f59 355
f80ccccb 356include::config/fsck.txt[]
1335f732 357
8daf3271 358include::config/gc.txt[]
48c32424 359
996f66eb 360include::config/gitcvs.txt[]
04752868 361
0648b769 362include::config/gitweb.txt[]
cd82323f 363
434e6e75 364include::config/grep.txt[]
ecd9ba61 365
ea555d04 366include::config/gpg.txt[]
b02f51b1 367
d864cf8b 368include::config/gui.txt[]
a2df1fb2 369
2c31a830 370include::config/guitool.txt[]
390c3480 371
d3df4270 372include::config/help.txt[]
b1f809d0 373
ad308479 374include::config/http.txt[]
6a56993b 375
8fc3f75f 376include::config/i18n.txt[]
d2c11a38 377
ae461026 378include::config/imap.txt[]
b0f34c3d 379
c1b342ad 380include::config/index.txt[]
3c09d684 381
ec335607 382include::config/init.txt[]
d8a8488d 383
cef9b951 384include::config/instaweb.txt[]
983a9eeb 385
630c2738 386include::config/interactive.txt[]
01143847 387
83009762 388include::config/log.txt[]
e6bb5f78 389
55e51cd7 390include::config/mailinfo.txt[]
d5c4b185 391
4a9f0c52 392include::config/mailmap.txt[]
08610900 393
f7ade6c9 394include::config/man.txt[]
7e8114c0 395
7fb5ab4a 396include::config/merge.txt[]
b5412484 397
ea24a76a 398include::config/mergetool.txt[]
682b451f 399
e50472d8 400include::config/notes.txt[]
6956f858 401
a168c5a2 402include::config/pack.txt[]
ae4f07fb 403
87e1b41a 404include::config/pager.txt[]
4370c2d6 405
cd967547 406include::config/pretty.txt[]
8028184e 407
dd55172c 408include::config/protocol.txt[]
373d70ef 409
7f50a495 410include::config/pull.txt[]
d8052750 411
d15dc439 412include::config/push.txt[]
b33a15b0 413
c7245900 414include::config/rebase.txt[]
16cf51c7 415
5f5a5fca 416include::config/receive.txt[]
0a1bc12b 417
99fce397 418include::config/remote.txt[]
737c5a9c 419
b720a9db 420include::config/remotes.txt[]
1918278e 421
be958be2 422include::config/repack.txt[]
ee34a2be 423
72622c24 424include::config/rerere.txt[]
b0f34c3d 425
e344b8b4 426include::config/reset.txt[]
4c3abd05 427
0ee42c86 428include::config/sendemail.txt[]
5453b83b 429
c3324199 430include::config/sequencer.txt[]
8dc9d22d 431
c52bcbb6 432include::config/showbranch.txt[]
1ab661dd 433
2ef0e469 434include::config/splitindex.txt[]
b2dd1c5c 435
12e60249
NTND
436include::config/ssh.txt[]
437
54ff5dda 438include::config/status.txt[]
4b2343fa 439
46a8bbb2 440include::config/stash.txt[]
3086c064 441
95c125f2 442include::config/submodule.txt[]
31224cbd 443
fb4c06fa 444include::config/tag.txt[]
ce1a79b6 445
81567caf
JH
446include::config/trace2.txt[]
447
4a5bad07 448include::config/transfer.txt[]
b0f34c3d 449
c61f5562 450include::config/uploadarchive.txt[]
7671b632 451
533fff6a 452include::config/uploadpack.txt[]
516e2b76 453
e4a7a7b0 454include::config/url.txt[]
1c2eafb8 455
18b421d4 456include::config/user.txt[]
d67778ec 457
25268ad5 458include::config/versionsort.txt[]
d811c8e1 459
07c11a0b 460include::config/web.txt[]
e92445a7 461
649cf589 462include::config/worktree.txt[]