git-show-ref --verify: Fail if called without a reference
[git/git.git] / Documentation / config.txt
CommitLineData
1ab661dd
PB
1CONFIGURATION FILE
2------------------
3
4The git configuration file contains a number of variables that affect
5ea5621f
JH
5the git command's behavior. `.git/config` file for each repository
6is used to store the information for that repository, and
7`$HOME/.gitconfig` is used to store per user information to give
8fallback values for `.git/config` file.
9
10They can be used by both the git plumbing
b8936cf0 11and the porcelains. The variables are divided into sections, where
1ab661dd
PB
12in the fully qualified variable name the variable itself is the last
13dot-separated segment and the section name is everything before the last
14dot. The variable names are case-insensitive and only alphanumeric
15characters are allowed. Some variables may appear multiple times.
16
e136f33b
JN
17Syntax
18~~~~~~
19
1ab661dd 20The syntax is fairly flexible and permissive; whitespaces are mostly
e136f33b
JN
21ignored. The '#' and ';' characters begin comments to the end of line,
22blank lines are ignored.
23
24The file consists of sections and variables. A section begins with
25the name of the section in square brackets and continues until the next
26section begins. Section names are not case sensitive. Only alphanumeric
27characters, '`-`' and '`.`' are allowed in section names. Each variable
28must belong to some section, which means that there must be section
29header before first setting of a variable.
30
31Sections can be further divided into subsections. To begin a subsection
32put its name in double quotes, separated by space from the section name,
33in the section header, like in example below:
34
35--------
36 [section "subsection"]
37
38--------
39
191453f6
JN
40Subsection names can contain any characters except newline (doublequote
41'`"`' and backslash have to be escaped as '`\"`' and '`\\`',
3dff5379 42respectively) and are case sensitive. Section header cannot span multiple
e136f33b
JN
43lines. Variables may belong directly to a section or to a given subsection.
44You can have `[section]` if you have `[section "subsection"]`, but you
45don't need to.
46
47There is also (case insensitive) alternative `[section.subsection]` syntax.
48In this syntax subsection names follow the same restrictions as for section
49name.
50
51All the other lines are recognized as setting variables, in the form
52'name = value'. If there is no equal sign on the line, the entire line
53is taken as 'name' and the variable is recognized as boolean "true".
54The variable names are case-insensitive and only alphanumeric
55characters and '`-`' are allowed. There can be more than one value
56for a given variable; we say then that variable is multivalued.
57
58Leading and trailing whitespace in a variable value is discarded.
59Internal whitespace within a variable value is retained verbatim.
60
61The values following the equals sign in variable assign are all either
62a string, an integer, or a boolean. Boolean values may be given as yes/no,
630/1 or true/false. Case is not significant in boolean values, when
64converting value to the canonical form using '--bool' type specifier;
e0d10e1c 65`git-config` will ensure that the output is "true" or "false".
e136f33b
JN
66
67String values may be entirely or partially enclosed in double quotes.
68You need to enclose variable value in double quotes if you want to
69preserve leading or trailing whitespace, or if variable value contains
70beginning of comment characters (if it contains '#' or ';').
71Double quote '`"`' and backslash '`\`' characters in variable value must
72be escaped: use '`\"`' for '`"`' and '`\\`' for '`\`'.
73
74The following escape sequences (beside '`\"`' and '`\\`') are recognized:
75'`\n`' for newline character (NL), '`\t`' for horizontal tabulation (HT, TAB)
76and '`\b`' for backspace (BS). No other char escape sequence, nor octal
77char sequences are valid.
78
79Variable value ending in a '`\`' is continued on the next line in the
80customary UNIX fashion.
81
82Some variables may require special value format.
1ab661dd
PB
83
84Example
85~~~~~~~
86
87 # Core variables
88 [core]
89 ; Don't trust file modes
90 filemode = false
91
92 # Our diff algorithm
93 [diff]
94 external = "/usr/local/bin/gnu-diff -u"
95 renames = true
96
910c00c8
AK
97 [branch "devel"]
98 remote = origin
99 merge = refs/heads/devel
100
e136f33b
JN
101 # Proxy settings
102 [core]
103 gitProxy="ssh" for "ssh://kernel.org/"
104 gitProxy=default-proxy ; for the rest
910c00c8 105
1ab661dd
PB
106Variables
107~~~~~~~~~
108
109Note that this list is non-comprehensive and not necessarily complete.
b8936cf0
FD
110For command-specific variables, you will find a more detailed description
111in the appropriate manual page. You will find a description of non-core
1ab661dd
PB
112porcelain configuration variables in the respective porcelain documentation.
113
114core.fileMode::
115 If false, the executable bit differences between the index and
116 the working copy are ignored; useful on broken filesystems like FAT.
117 See gitlink:git-update-index[1]. True by default.
118
119core.gitProxy::
120 A "proxy command" to execute (as 'command host port') instead
121 of establishing direct connection to the remote server when
122 using the git protocol for fetching. If the variable value is
123 in the "COMMAND for DOMAIN" format, the command is applied only
124 on hostnames ending with the specified domain string. This variable
125 may be set multiple times and is matched in the given order;
126 the first match wins.
b8936cf0
FD
127+
128Can be overridden by the 'GIT_PROXY_COMMAND' environment variable
129(which always applies universally, without the special "for"
130handling).
1ab661dd
PB
131
132core.ignoreStat::
133 The working copy files are assumed to stay unchanged until you
134 mark them otherwise manually - Git will not detect the file changes
135 by lstat() calls. This is useful on systems where those are very
136 slow, such as Microsoft Windows. See gitlink:git-update-index[1].
137 False by default.
138
9f0bb90d
JH
139core.preferSymlinkRefs::
140 Instead of the default "symref" format for HEAD
141 and other symbolic reference files, use symbolic links.
142 This is sometimes needed to work with old scripts that
143 expect HEAD to be a symbolic link.
1ab661dd 144
e4a15f40
SP
145core.bare::
146 If true this repository is assumed to be 'bare' and has no
147 working directory associated with it. If this is the case a
148 number of commands that require a working directory will be
149 disabled, such as gitlink:git-add[1] or gitlink:git-merge[1].
150+
151This setting is automatically guessed by gitlink:git-clone[1] or
152gitlink:git-init[1] when the repository was created. By default a
153repository that ends in "/.git" is assumed to be not bare (bare =
154false), while all other repositories are assumed to be bare (bare
155= true).
156
6de08ae6 157core.logAllRefUpdates::
4057deb5
JH
158 Updates to a ref <ref> is logged to the file
159 "$GIT_DIR/logs/<ref>", by appending the new and old
160 SHA1, the date/time and the reason of the update, but
161 only when the file exists. If this configuration
162 variable is set to true, missing "$GIT_DIR/logs/<ref>"
163 file is automatically created for branch heads.
a862f97e
JH
164+
165This information can be used to determine what commit
166was the tip of a branch "2 days ago".
167+
168This value is true by default in a repository that has
169a working directory associated with it, and false by
170default in a bare repository.
6de08ae6 171
1ab661dd
PB
172core.repositoryFormatVersion::
173 Internal variable identifying the repository format and layout
174 version.
175
176core.sharedRepository::
d5dc6a76
JF
177 When 'group' (or 'true'), the repository is made shareable between
178 several users in a group (making sure all the files and objects are
179 group-writable). When 'all' (or 'world' or 'everybody'), the
180 repository will be readable by all users, additionally to being
181 group-shareable. When 'umask' (or 'false'), git will use permissions
5c94f87e 182 reported by umask(2). See gitlink:git-init[1]. False by default.
1ab661dd
PB
183
184core.warnAmbiguousRefs::
185 If true, git will warn you if the ref name you passed it is ambiguous
186 and might match multiple refs in the .git/refs/ tree. True by default.
187
3d3e95af 188core.compression::
12f6c308
JBH
189 An integer -1..9, indicating the compression level for objects that
190 are not in a pack file. -1 is the zlib and git default. 0 means no
191 compression, and 1..9 are various speed/size tradeoffs, 9 being
192 slowest.
193
93821bd9
LT
194core.legacyheaders::
195 A boolean which enables the legacy object header format in case
196 you want to interoperate with old clients accessing the object
197 database directly (where the "http://" and "rsync://" protocols
198 count as direct access).
199
60bb8b14
SP
200core.packedGitWindowSize::
201 Number of bytes of a pack file to map into memory in a
202 single mapping operation. Larger window sizes may allow
203 your system to process a smaller number of large pack files
204 more quickly. Smaller window sizes will negatively affect
eb92242f 205 performance due to increased calls to the operating system's
60bb8b14 206 memory manager, but may improve performance when accessing
22bac0ea
SP
207 a large number of large pack files.
208+
209Default is 1 MiB if NO_MMAP was set at compile time, otherwise 32
210MiB on 32 bit platforms and 1 GiB on 64 bit platforms. This should
211be reasonable for all users/operating systems. You probably do
212not need to adjust this value.
eb92242f
SP
213+
214Common unit suffixes of 'k', 'm', or 'g' are supported.
60bb8b14 215
77ccc5bb
SP
216core.packedGitLimit::
217 Maximum number of bytes to map simultaneously into memory
218 from pack files. If Git needs to access more than this many
219 bytes at once to complete an operation it will unmap existing
220 regions to reclaim virtual address space within the process.
22bac0ea
SP
221+
222Default is 256 MiB on 32 bit platforms and 8 GiB on 64 bit platforms.
223This should be reasonable for all users/operating systems, except on
224the largest projects. You probably do not need to adjust this value.
eb92242f
SP
225+
226Common unit suffixes of 'k', 'm', or 'g' are supported.
77ccc5bb 227
4514ad4f
PB
228alias.*::
229 Command aliases for the gitlink:git[1] command wrapper - e.g.
230 after defining "alias.last = cat-file commit HEAD", the invocation
231 "git last" is equivalent to "git cat-file commit HEAD". To avoid
99b41c84
PB
232 confusion and troubles with script usage, aliases that
233 hide existing git commands are ignored. Arguments are split by
234 spaces, the usual shell quoting and escaping is supported.
235 quote pair and a backslash can be used to quote them.
4514ad4f 236
dfd42a3c
TT
237 If the alias expansion is prefixed with an exclamation point,
238 it will be treated as a shell command. For example, defining
239 "alias.new = !gitk --all --not ORIG_HEAD", the invocation
240 "git new" is equivalent to running the shell command
241 "gitk --all --not ORIG_HEAD".
242
1ab661dd
PB
243apply.whitespace::
244 Tells `git-apply` how to handle whitespaces, in the same way
245 as the '--whitespace' option. See gitlink:git-apply[1].
246
648ad18f
SB
247branch.<name>.remote::
248 When in branch <name>, it tells `git fetch` which remote to fetch.
62b339a5 249 If this option is not given, `git fetch` defaults to remote "origin".
648ad18f 250
5372806a 251branch.<name>.merge::
62b339a5
JW
252 When in branch <name>, it tells `git fetch` the default refspec to
253 be marked for merging in FETCH_HEAD. The value has exactly to match
254 a remote part of one of the refspecs which are fetched from the remote
255 given by "branch.<name>.remote".
256 The merge information is used by `git pull` (which at first calls
257 `git fetch`) to lookup the default branch for merging. Without
258 this option, `git pull` defaults to merge the first refspec fetched.
259 Specify multiple values to get an octopus merge.
5372806a 260
f3673988
BG
261color.branch::
262 A boolean to enable/disable color in the output of
263 gitlink:git-branch[1]. May be set to `true` (or `always`),
264 `false` (or `never`) or `auto`, in which case colors are used
265 only when the output is to a terminal. Defaults to false.
266
267color.branch.<slot>::
268 Use customized color for branch coloration. `<slot>` is one of
269 `current` (the current branch), `local` (a local branch),
270 `remote` (a tracking branch in refs/remotes/), `plain` (other
4f193f20
MW
271 refs).
272+
273The value for these configuration variables is a list of colors (at most
274two) and attributes (at most one), separated by spaces. The colors
275accepted are `normal`, `black`, `red`, `green`, `yellow`, `blue`,
276`magenta`, `cyan` and `white`; the attributes are `bold`, `dim`, `ul`,
277`blink` and `reverse`. The first color given is the foreground; the
278second is the background. The position of the attribute, if any,
279doesn't matter.
f3673988 280
a159ca0c 281color.diff::
b5376648
JH
282 When true (or `always`), always use colors in patch.
283 When false (or `never`), never. When set to `auto`, use
284 colors only when the output is to the terminal.
285
a159ca0c 286color.diff.<slot>::
4f193f20
MW
287 Use customized color for diff colorization. `<slot>` specifies
288 which part of the patch to use the specified color, and is one
289 of `plain` (context text), `meta` (metainformation), `frag`
290 (hunk header), `old` (removed lines), `new` (added lines),
291 `commit` (commit headers), or `whitespace` (highlighting dubious
292 whitespace). The values of these variables may be specified as
293 in color.branch.<slot>.
b5376648 294
1d77043b
JH
295color.pager::
296 A boolean to enable/disable colored output when the pager is in
297 use (default is true).
298
299color.status::
300 A boolean to enable/disable color in the output of
301 gitlink:git-status[1]. May be set to `true` (or `always`),
302 `false` (or `never`) or `auto`, in which case colors are used
303 only when the output is to a terminal. Defaults to false.
304
305color.status.<slot>::
306 Use customized color for status colorization. `<slot>` is
307 one of `header` (the header text of the status message),
82dca848
SP
308 `added` or `updated` (files which are added but not committed),
309 `changed` (files which are changed but not added in the index),
1d77043b 310 or `untracked` (files which are not tracked by git). The values of
f3673988 311 these variables may be specified as in color.branch.<slot>.
1d77043b 312
1ab661dd
PB
313diff.renameLimit::
314 The number of files to consider when performing the copy/rename
315 detection; equivalent to the git diff option '-l'.
316
b68ea12e
EW
317diff.renames::
318 Tells git to detect renames. If set to any boolean value, it
319 will enable basic rename detection. If set to "copies" or
320 "copy", it will detect copies, as well.
321
af7cf268
JH
322fetch.unpackLimit::
323 If the number of objects fetched over the git native
324 transfer is below this
325 limit, then the objects will be unpacked into loose object
326 files. However if the number of received objects equals or
327 exceeds this limit then the received pack will be stored as
328 a pack, after adding any missing delta bases. Storing the
329 pack from a push can make the push operation complete faster,
330 especially on slow filesystems.
331
1ab661dd
PB
332format.headers::
333 Additional email headers to include in a patch to be submitted
334 by mail. See gitlink:git-format-patch[1].
335
c2120e5e
JS
336gc.packrefs::
337 `git gc` does not run `git pack-refs` in a bare repository by
338 default so that older dumb-transport clients can still fetch
339 from the repository. Setting this to `true` lets `git
340 gc` to run `git pack-refs`. Setting this to `false` tells
341 `git gc` never to run `git pack-refs`. The default setting is
342 `notbare`. Enable it only when you know you do not have to
343 support such clients. The default setting will change to `true`
344 at some stage, and setting this to `false` will continue to
345 prevent `git pack-refs` from being run from `git gc`.
346
4aec56d1
JH
347gc.reflogexpire::
348 `git reflog expire` removes reflog entries older than
349 this time; defaults to 90 days.
350
351gc.reflogexpireunreachable::
352 `git reflog expire` removes reflog entries older than
353 this time and are not reachable from the current tip;
354 defaults to 30 days.
355
48c32424
JH
356gc.rerereresolved::
357 Records of conflicted merge you resolved earlier are
358 kept for this many days when `git rerere gc` is run.
359 The default is 60 days. See gitlink:git-rerere[1].
360
361gc.rerereunresolved::
362 Records of conflicted merge you have not resolved are
363 kept for this many days when `git rerere gc` is run.
364 The default is 15 days. See gitlink:git-rerere[1].
365
1ab661dd
PB
366gitcvs.enabled::
367 Whether the cvs pserver interface is enabled for this repository.
368 See gitlink:git-cvsserver[1].
369
370gitcvs.logfile::
371 Path to a log file where the cvs pserver interface well... logs
372 various stuff. See gitlink:git-cvsserver[1].
373
374http.sslVerify::
375 Whether to verify the SSL certificate when fetching or pushing
37425065 376 over HTTPS. Can be overridden by the 'GIT_SSL_NO_VERIFY' environment
1ab661dd
PB
377 variable.
378
379http.sslCert::
380 File containing the SSL certificate when fetching or pushing
37425065 381 over HTTPS. Can be overridden by the 'GIT_SSL_CERT' environment
1ab661dd
PB
382 variable.
383
384http.sslKey::
385 File containing the SSL private key when fetching or pushing
abda1ef5 386 over HTTPS. Can be overridden by the 'GIT_SSL_KEY' environment
1ab661dd
PB
387 variable.
388
389http.sslCAInfo::
390 File containing the certificates to verify the peer with when
abda1ef5 391 fetching or pushing over HTTPS. Can be overridden by the
1ab661dd
PB
392 'GIT_SSL_CAINFO' environment variable.
393
394http.sslCAPath::
395 Path containing files with the CA certificates to verify the peer
37425065 396 with when fetching or pushing over HTTPS. Can be overridden
1ab661dd
PB
397 by the 'GIT_SSL_CAPATH' environment variable.
398
399http.maxRequests::
abda1ef5 400 How many HTTP requests to launch in parallel. Can be overridden
1ab661dd
PB
401 by the 'GIT_HTTP_MAX_REQUESTS' environment variable. Default is 5.
402
403http.lowSpeedLimit, http.lowSpeedTime::
404 If the HTTP transfer speed is less than 'http.lowSpeedLimit'
405 for longer than 'http.lowSpeedTime' seconds, the transfer is aborted.
abda1ef5 406 Can be overridden by the 'GIT_HTTP_LOW_SPEED_LIMIT' and
1ab661dd
PB
407 'GIT_HTTP_LOW_SPEED_TIME' environment variables.
408
3ea099d4
SK
409http.noEPSV::
410 A boolean which disables using of EPSV ftp command by curl.
411 This can helpful with some "poor" ftp servers which doesn't
412 support EPSV mode. Can be overridden by the 'GIT_CURL_FTP_NO_EPSV'
413 environment variable. Default is false (curl will use EPSV).
414
1ab661dd
PB
415i18n.commitEncoding::
416 Character encoding the commit messages are stored in; git itself
417 does not care per se, but this information is necessary e.g. when
418 importing commits from emails or in the gitk graphical history
419 browser (and possibly at other places in the future or in other
420 porcelains). See e.g. gitlink:git-mailinfo[1]. Defaults to 'utf-8'.
421
d2c11a38
JH
422i18n.logOutputEncoding::
423 Character encoding the commit messages are converted to when
424 running `git-log` and friends.
425
0f03ca94
PB
426log.showroot::
427 If true, the initial commit will be shown as a big creation event.
428 This is equivalent to a diff against an empty tree.
429 Tools like gitlink:git-log[1] or gitlink:git-whatchanged[1], which
430 normally hide the root commit will now show it. True by default.
431
1ab661dd
PB
432merge.summary::
433 Whether to include summaries of merged commits in newly created
434 merge commit messages. False by default.
435
8c3275ab
SP
436merge.verbosity::
437 Controls the amount of output shown by the recursive merge
438 strategy. Level 0 outputs nothing except a final error
439 message if conflicts were detected. Level 1 outputs only
440 conflicts, 2 outputs conflicts and file changes. Level 5 and
441 above outputs debugging information. The default is level 2.
442
4812a93a
JK
443pack.window::
444 The size of the window used by gitlink:git-pack-objects[1] when no
445 window size is given on the command line. Defaults to 10.
446
1ab661dd
PB
447pull.octopus::
448 The default merge strategy to use when pulling multiple branches
449 at once.
450
451pull.twohead::
452 The default merge strategy to use when pulling a single branch.
453
0cc6d346
SB
454remote.<name>.url::
455 The URL of a remote repository. See gitlink:git-fetch[1] or
456 gitlink:git-push[1].
457
458remote.<name>.fetch::
459 The default set of "refspec" for gitlink:git-fetch[1]. See
460 gitlink:git-fetch[1].
461
462remote.<name>.push::
463 The default set of "refspec" for gitlink:git-push[1]. See
464 gitlink:git-push[1].
465
060aafc1 466remote.<name>.receivepack::
5dee29ac 467 The default program to execute on the remote side when pushing. See
060aafc1
UKK
468 option \--exec of gitlink:git-push[1].
469
5dee29ac
UKK
470remote.<name>.uploadpack::
471 The default program to execute on the remote side when fetching. See
472 option \--exec of gitlink:git-fetch-pack[1].
473
b6945f57
JH
474repack.usedeltabaseoffset::
475 Allow gitlink:git-repack[1] to create packs that uses
476 delta-base offset. Defaults to false.
477
1ab661dd
PB
478show.difftree::
479 The default gitlink:git-diff-tree[1] arguments to be used
480 for gitlink:git-show[1].
481
482showbranch.default::
483 The default set of branches for gitlink:git-show-branch[1].
484 See gitlink:git-show-branch[1].
485
ce1a79b6 486tar.umask::
7fe08af4 487 By default, gitlink:git-tar-tree[1] sets file and directories modes
ce1a79b6
WT
488 to 0666 or 0777. While this is both useful and acceptable for projects
489 such as the Linux Kernel, it might be excessive for other projects.
490 With this variable, it becomes possible to tell
7fe08af4 491 gitlink:git-tar-tree[1] to apply a specific umask to the modes above.
ce1a79b6
WT
492 The special value "user" indicates that the user's current umask will
493 be used. This should be enough for most projects, as it will lead to
7fe08af4 494 the same permissions as gitlink:git-checkout[1] would use. The default
ce1a79b6
WT
495 value remains 0, which means world read-write.
496
1ab661dd
PB
497user.email::
498 Your email address to be recorded in any newly created commits.
abda1ef5 499 Can be overridden by the 'GIT_AUTHOR_EMAIL' and 'GIT_COMMITTER_EMAIL'
1ab661dd
PB
500 environment variables. See gitlink:git-commit-tree[1].
501
502user.name::
503 Your full name to be recorded in any newly created commits.
abda1ef5 504 Can be overridden by the 'GIT_AUTHOR_NAME' and 'GIT_COMMITTER_NAME'
1ab661dd
PB
505 environment variables. See gitlink:git-commit-tree[1].
506
d67778ec
AP
507user.signingkey::
508 If gitlink:git-tag[1] is not selecting the key you want it to
509 automatically when creating a signed tag, you can override the
510 default selection with this variable. This option is passed
511 unchanged to gpg's --local-user parameter, so you may specify a key
512 using any method that gpg supports.
513
1ab661dd
PB
514whatchanged.difftree::
515 The default gitlink:git-diff-tree[1] arguments to be used
516 for gitlink:git-whatchanged[1].
517
518imap::
519 The configuration variables in the 'imap' section are described
520 in gitlink:git-imap-send[1].
199a9218 521
fc04c412
SP
522receive.unpackLimit::
523 If the number of objects received in a push is below this
524 limit then the objects will be unpacked into loose object
525 files. However if the number of received objects equals or
526 exceeds this limit then the received pack will be stored as
527 a pack, after adding any missing delta bases. Storing the
528 pack from a push can make the push operation complete faster,
529 especially on slow filesystems.
530
531receive.denyNonFastForwards::
199a9218
JS
532 If set to true, git-receive-pack will deny a ref update which is
533 not a fast forward. Use this to prevent such an update via a push,
534 even if that push is forced. This configuration variable is
535 set when initializing a shared repository.
536
e28714c5
JH
537transfer.unpackLimit::
538 When `fetch.unpackLimit` or `receive.unpackLimit` are
539 not set, the value of this variable is used instead.
540
541