Sixth batch
[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
1925fe0c
181----
182# Core variables
183[core]
184 ; Don't trust file modes
185 filemode = false
186
187# Our diff algorithm
188[diff]
189 external = /usr/local/bin/diff-wrapper
190 renames = true
191
192[branch "devel"]
193 remote = origin
194 merge = refs/heads/devel
195
196# Proxy settings
197[core]
198 gitProxy="ssh" for "kernel.org"
199 gitProxy=default-proxy ; for the rest
200
201[include]
202 path = /path/to/foo.inc ; include by absolute path
203 path = foo.inc ; find "foo.inc" relative to the current file
204 path = ~/foo.inc ; find "foo.inc" in your `$HOME` directory
205
206; include if $GIT_DIR is /path/to/foo/.git
207[includeIf "gitdir:/path/to/foo/.git"]
208 path = /path/to/foo.inc
209
210; include for all repositories inside /path/to/group
211[includeIf "gitdir:/path/to/group/"]
212 path = /path/to/foo.inc
213
214; include for all repositories inside $HOME/to/group
215[includeIf "gitdir:~/to/group/"]
216 path = /path/to/foo.inc
217
218; relative paths are always relative to the including
219; file (if the condition is true); their location is not
220; affected by the condition
221[includeIf "gitdir:/path/to/group/"]
222 path = foo.inc
223----
994cd6c7 224
07b2c0ea
DL
225 ; include only if we are in a worktree where foo-branch is
226 ; currently checked out
227 [includeIf "onbranch:foo-branch"]
228 path = foo.inc
229
5f7b91ba
JH
230Values
231~~~~~~
232
233Values of many variables are treated as a simple string, but there
234are variables that take values of specific types and there are rules
235as to how to spell them.
236
237boolean::
238
239 When a variable is said to take a boolean value, many
240 synonyms are accepted for 'true' and 'false'; these are all
241 case-insensitive.
242
7f0a02be
AH
243 true;; Boolean true literals are `yes`, `on`, `true`,
244 and `1`. Also, a variable defined without `= <value>`
5f7b91ba
JH
245 is taken as true.
246
7f0a02be
AH
247 false;; Boolean false literals are `no`, `off`, `false`,
248 `0` and the empty string.
5f7b91ba 249+
ed3bb3df 250When converting a value to its canonical form using the `--type=bool` type
7f0a02be 251specifier, 'git config' will ensure that the output is "true" or
5f7b91ba
JH
252"false" (spelled in lowercase).
253
254integer::
255 The value for many variables that specify various sizes can
256 be suffixed with `k`, `M`,... to mean "scale the number by
257 1024", "by 1024x1024", etc.
258
b92c1a28 259color::
adb33566
JK
260 The value for a variable that takes a color is a list of
261 colors (at most two, one for foreground and one for background)
262 and attributes (as many as you want), separated by spaces.
5f456b3c 263+
adb33566
JK
264The basic colors accepted are `normal`, `black`, `red`, `green`, `yellow`,
265`blue`, `magenta`, `cyan` and `white`. The first color given is the
266foreground; the second is the background.
5ee87585 267+
adb33566
JK
268Colors may also be given as numbers between 0 and 255; these use ANSI
269256-color mode (but note that not all terminals may support this). If
270your terminal supports it, you may also specify 24-bit RGB values as
271hex, like `#ff0ab3`.
272+
9dc3515c
JK
273The accepted attributes are `bold`, `dim`, `ul`, `blink`, `reverse`,
274`italic`, and `strike` (for crossed-out or "strikethrough" letters).
275The position of any attributes with respect to the colors
54590a0e
JK
276(before, after, or in between), doesn't matter. Specific attributes may
277be turned off by prefixing them with `no` or `no-` (e.g., `noreverse`,
278`no-ul`, etc).
adb33566 279+
512aba26
JK
280An empty color string produces no color effect at all. This can be used
281to avoid coloring specific elements without disabling color entirely.
282+
adb33566
JK
283For git's pre-defined color slots, the attributes are meant to be reset
284at the beginning of each item in the colored output. So setting
285`color.decorate.branch` to `black` will paint that branch name in a
286plain `black`, even if the previous thing on the same output line (e.g.
287opening parenthesis before the list of branch names in `log --decorate`
288output) is set to be painted with `bold` or some other attribute.
289However, custom log formats may do more complicated and layered
290coloring, and the negated forms may be useful there.
b92c1a28 291
dca83abd
JH
292pathname::
293 A variable that takes a pathname value can be given a
294 string that begins with "`~/`" or "`~user/`", and the usual
295 tilde expansion happens to such a string: `~/`
296 is expanded to the value of `$HOME`, and `~user/` to the
297 specified user's home directory.
298
5f7b91ba 299
1ab661dd
PB
300Variables
301~~~~~~~~~
302
303Note that this list is non-comprehensive and not necessarily complete.
b8936cf0 304For command-specific variables, you will find a more detailed description
93728b23
CA
305in the appropriate manual page.
306
307Other git-related tools may and do use their own variables. When
308inventing new variables for use in your own tool, make sure their
309names do not conflict with those that are used by Git itself and
310other popular tools, and describe them in your documentation.
311
838ef420 312include::config/advice.txt[]
75194438 313
1a394fa9 314include::config/core.txt[]
dce96489 315
29120d8e 316include::config/add.txt[]
13bd2134 317
f740c8f1 318include::config/alias.txt[]
dfd42a3c 319
d293ffef 320include::config/am.txt[]
e97a5e76 321
696d4796 322include::config/apply.txt[]
1ab661dd 323
d09467b6 324include::config/blame.txt[]
8578037b 325
7273b95d 326include::config/branch.txt[]
a5ba2cbe 327
6b0b9740 328include::config/browser.txt[]
584627b4 329
9140b410 330include::config/checkout.txt[]
fa655d84 331
328e629c 332include::config/clean.txt[]
2122591b 333
0a7839e3 334include::config/color.txt[]
6b2f2d98 335
dbfc949f 336include::config/column.txt[]
d96e3c15 337
5453d236 338include::config/commit.txt[]
aaab8420 339
3a49be6d 340include::config/credential.txt[]
7f4d4746 341
2b4b7305 342include::config/completion.txt[]
6532f374 343
fa922d74 344include::config/diff.txt[]
afcbc8e7 345
9155f6f6 346include::config/difftool.txt[]
a904392e 347
f2e58246 348include::config/fastimport.txt[]
d9545c7f 349
c6cc4c5a
DS
350include::config/feature.txt[]
351
561fda20 352include::config/fetch.txt[]
42cc7485 353
ab14f494 354include::config/format.txt[]
bb52995f 355
734dfebb 356include::config/filter.txt[]
26488f59 357
f80ccccb 358include::config/fsck.txt[]
1335f732 359
8daf3271 360include::config/gc.txt[]
48c32424 361
996f66eb 362include::config/gitcvs.txt[]
04752868 363
0648b769 364include::config/gitweb.txt[]
cd82323f 365
434e6e75 366include::config/grep.txt[]
ecd9ba61 367
ea555d04 368include::config/gpg.txt[]
b02f51b1 369
d864cf8b 370include::config/gui.txt[]
a2df1fb2 371
2c31a830 372include::config/guitool.txt[]
390c3480 373
d3df4270 374include::config/help.txt[]
b1f809d0 375
ad308479 376include::config/http.txt[]
6a56993b 377
8fc3f75f 378include::config/i18n.txt[]
d2c11a38 379
ae461026 380include::config/imap.txt[]
b0f34c3d 381
c1b342ad 382include::config/index.txt[]
3c09d684 383
ec335607 384include::config/init.txt[]
d8a8488d 385
cef9b951 386include::config/instaweb.txt[]
983a9eeb 387
630c2738 388include::config/interactive.txt[]
01143847 389
83009762 390include::config/log.txt[]
e6bb5f78 391
55e51cd7 392include::config/mailinfo.txt[]
d5c4b185 393
4a9f0c52 394include::config/mailmap.txt[]
08610900 395
f7ade6c9 396include::config/man.txt[]
7e8114c0 397
7fb5ab4a 398include::config/merge.txt[]
b5412484 399
ea24a76a 400include::config/mergetool.txt[]
682b451f 401
e50472d8 402include::config/notes.txt[]
6956f858 403
a168c5a2 404include::config/pack.txt[]
ae4f07fb 405
87e1b41a 406include::config/pager.txt[]
4370c2d6 407
cd967547 408include::config/pretty.txt[]
8028184e 409
dd55172c 410include::config/protocol.txt[]
373d70ef 411
7f50a495 412include::config/pull.txt[]
d8052750 413
d15dc439 414include::config/push.txt[]
b33a15b0 415
c7245900 416include::config/rebase.txt[]
16cf51c7 417
5f5a5fca 418include::config/receive.txt[]
0a1bc12b 419
99fce397 420include::config/remote.txt[]
737c5a9c 421
b720a9db 422include::config/remotes.txt[]
1918278e 423
be958be2 424include::config/repack.txt[]
ee34a2be 425
72622c24 426include::config/rerere.txt[]
b0f34c3d 427
e344b8b4 428include::config/reset.txt[]
4c3abd05 429
0ee42c86 430include::config/sendemail.txt[]
5453b83b 431
c3324199 432include::config/sequencer.txt[]
8dc9d22d 433
c52bcbb6 434include::config/showbranch.txt[]
1ab661dd 435
2ef0e469 436include::config/splitindex.txt[]
b2dd1c5c 437
12e60249
NTND
438include::config/ssh.txt[]
439
54ff5dda 440include::config/status.txt[]
4b2343fa 441
46a8bbb2 442include::config/stash.txt[]
3086c064 443
95c125f2 444include::config/submodule.txt[]
31224cbd 445
fb4c06fa 446include::config/tag.txt[]
ce1a79b6 447
81567caf
JH
448include::config/trace2.txt[]
449
4a5bad07 450include::config/transfer.txt[]
b0f34c3d 451
c61f5562 452include::config/uploadarchive.txt[]
7671b632 453
533fff6a 454include::config/uploadpack.txt[]
516e2b76 455
e4a7a7b0 456include::config/url.txt[]
1c2eafb8 457
18b421d4 458include::config/user.txt[]
d67778ec 459
25268ad5 460include::config/versionsort.txt[]
d811c8e1 461
07c11a0b 462include::config/web.txt[]
e92445a7 463
649cf589 464include::config/worktree.txt[]