config.txt 103 KB
Newer Older
1 2 3

4 5
The Git configuration file contains a number of variables that affect
the Git commands' behavior. The `.git/config` file in each repository
6 7
is used to store the configuration for that repository, and
`$HOME/.gitconfig` is used to store a per-user configuration as
fallback values for the `.git/config` file. The file `/etc/gitconfig`
can be used to store a system-wide default configuration.

The configuration variables are used by both the Git plumbing
12 13
and the porcelains. The variables are divided into sections, wherein
the fully qualified variable name of the variable itself is the last
dot-separated segment and the section name is everything before the last
15 16 17
dot. The variable names are case-insensitive, allow only alphanumeric
characters and `-`, and must start with an alphabetic character.  Some
variables may appear multiple times.

19 20 21

The syntax is fairly flexible and permissive; whitespaces are mostly
23 24 25 26 27 28
ignored.  The '#' and ';' characters begin comments to the end of line,
blank lines are ignored.

The file consists of sections and variables.  A section begins with
the name of the section in square brackets and continues until the next
section begins.  Section names are not case sensitive.  Only alphanumeric
characters, `-` and `.` are allowed in section names.  Each variable
30 31
must belong to some section, which means that there must be a section
header before the first setting of a variable.
32 33 34

Sections can be further divided into subsections.  To begin a subsection
put its name in double quotes, separated by space from the section name,
in the section header, like in the example below:
36 37 38 39 40 41

	[section "subsection"]


42 43 44
Subsection names are case sensitive and can contain any characters except
newline (doublequote `"` and backslash have to be escaped as `\"` and `\\`,
respectively).  Section headers cannot span multiple
45 46 47 48
lines.  Variables may belong directly to a section or to a given subsection.
You can have `[section]` if you have `[section "subsection"]`, but you
don't need to.

49 50 51 52
There is also a deprecated `[section.subsection]` syntax. With this
syntax, the subsection name is converted to lower-case and is also
compared case sensitively. These subsection names follow the same
restrictions as section names.

54 55
All the other lines (and the remainder of the line after the section
header) are recognized as setting variables, in the form
56 57
'name = value'.  If there is no equal sign on the line, the entire line
is taken as 'name' and the variable is recognized as boolean "true".
58 59 60 61
The variable names are case-insensitive, allow only alphanumeric characters
and `-`, and must start with an alphabetic character.  There can be more
than one value for a given variable; we say then that the variable is
62 63 64 65 66 67

Leading and trailing whitespace in a variable value is discarded.
Internal whitespace within a variable value is retained verbatim.

The values following the equals sign in variable assign are all either
a string, an integer, or a boolean.  Boolean values may be given as yes/no,
1/0, true/false or on/off.  Case is not significant in boolean values, when
converting value to the canonical form using '--bool' type specifier;
'git config' will ensure that the output is "true" or "false".
71 72

String values may be entirely or partially enclosed in double quotes.
73 74 75 76
You need to enclose variable values in double quotes if you want to
preserve leading or trailing whitespace, or if the variable value contains
comment characters (i.e. it contains '#' or ';').
Double quote `"` and backslash `\` characters in variable values must
be escaped: use `\"` for `"` and `\\` for `\`.

79 80
The following escape sequences (beside `\"` and `\\`) are recognized:
`\n` for newline character (NL), `\t` for horizontal tabulation (HT, TAB)
81 82
and `\b` for backspace (BS).  Other char escape sequences (including octal
escape sequences) are invalid.

Variable values ending in a `\` are continued on the next line in the
85 86
customary UNIX fashion.

Some variables may require a special value format.

Jeff King's avatar
Jeff King committed
89 90 91 92 93 94 95 96 97

You can include one config file from another by setting the special
`include.path` variable to the name of the file to be included. The
included file is expanded immediately, as if its contents had been
found at the location of the include directive. If the value of the
`include.path` variable is a relative path, the path is considered to be
relative to the configuration file in which the include directive was
Jeff King's avatar
Jeff King committed
98 99
found. The value of `include.path` is subject to tilde expansion: `~/`
is expanded to the value of `$HOME`, and `~user/` to the specified
user's home directory. See below for examples.
Jeff King's avatar
Jeff King committed

102 103 104 105 106 107 108 109 110 111

	# Core variables
		; Don't trust file modes
		filemode = false

	# Our diff algorithm
		external = /usr/local/bin/diff-wrapper
113 114
		renames = true

115 116 117 118
	[branch "devel"]
		remote = origin
		merge = refs/heads/devel

119 120
	# Proxy settings
		gitProxy="ssh" for ""
		gitProxy=default-proxy ; for the rest

Jeff King's avatar
Jeff King committed
124 125 126
		path = /path/to/ ; include by absolute path
		path = foo ; expand "foo" relative to the current file
		path = ~/foo ; expand "foo" in your $HOME directory
Jeff King's avatar
Jeff King committed

129 130 131 132

Note that this list is non-comprehensive and not necessarily complete.
For command-specific variables, you will find a more detailed description
134 135 136 137 138 139 140
in the appropriate manual page.

Other git-related tools may and do use their own variables.  When
inventing new variables for use in your own tool, make sure their
names do not conflict with those that are used by Git itself and
other popular tools, and describe them in your documentation.


143 144 145
	These variables control various optional help messages designed to
	aid new users. All 'advice.*' variables default to 'true', and you
	can tell Git that you do not need help by setting these to 'false':
146 147
		Set this variable to 'false' if you want to disable
151 152
		'pushNonFFMatching', 'pushAlreadyExists',
		'pushFetchFirst', and 'pushNeedsForce'
154 155 156 157 158 159 160 161
		Advice shown when linkgit:git-push[1] fails due to a
		non-fast-forward update to the current branch.
		Advice shown when you ran linkgit:git-push[1] and pushed
		'matching refs' explicitly (i.e. you used ':', or
		specified a refspec that isn't your current branch) and
		it resulted in a non-fast-forward error.
162 163 164
		Shown when linkgit:git-push[1] rejects an update that
		does not qualify for fast-forwarding (e.g., a tag.)
165 166 167 168 169 170 171
		Shown when linkgit:git-push[1] rejects an update that
		tries to overwrite a remote ref that points at an
		object we do not have.
		Shown when linkgit:git-push[1] rejects an update that
		tries to overwrite a remote ref that points at an
172 173
		object that is not a commit-ish, or make the remote
		ref point at an object that is not a commit-ish.
		Show directions on how to proceed from the current
		state in the output of linkgit:git-status[1], in
		the template shown when writing commit messages in
178 179
		linkgit:git-commit[1], and in the help message shown
		by linkgit:git-checkout[1] when switching branch.
180 181 182 183
		Advise to consider using the `-u` option to linkgit:git-status[1]
		when the command takes more than 2 seconds to enumerate untracked
184 185
		Advice shown when linkgit:git-merge[1] refuses to
		merge to avoid overwriting local changes.
		Advice shown by various commands when conflicts
		prevent the operation from being performed.
190 191 192
		Advice on how to set your identity configuration when
		your information is guessed from the system username and
		domain name.
		Advice shown when you used linkgit:git-checkout[1] to
		move to the detach HEAD state, to instruct how to create
		a local branch after the fact.
198 199 200
		Advice that shows the location of the patch file when
		linkgit:git-am[1] fails to apply it.
201 202 203
		In case of failure in the output of linkgit:git-rm[1],
		show directions on how to proceed from the current state.
204 205

207 208
	Tells Git if the executable bit of files in the working tree
	is to be honored.
210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226
Some filesystems lose the executable bit when a file that is
marked as executable is checked out, or checks out an
non-executable file with executable bit on.
linkgit:git-clone[1] or linkgit:git-init[1] probe the filesystem
to see if it handles the executable bit correctly
and this variable is automatically set as necessary.
A repository, however, may be on a filesystem that handles
the filemode correctly, and this variable is set to 'true'
when created, but later may be made accessible from another
environment that loses the filemode (e.g. exporting ext4 via
CIFS mount, visiting a Cygwin created repository with
Git for Windows or Eclipse).
In such a case it may be necessary to set this variable to 'false'.
See linkgit:git-update-index[1].
The default is true (when core.filemode is not specified in the config file).

228 229
	If true, this option enables various workarounds to enable
	Git to work better on filesystems that are not case sensitive,
	like FAT. For example, if a directory listing finds
	"makefile" when Git expects "Makefile", Git will assume
233 234 235 236 237 238 239
	it is really the same file, and continue to remember it as
The default is false, except linkgit:git-clone[1] or linkgit:git-init[1]
will probe and set core.ignorecase true if appropriate when the repository
is created.

241 242
	This option is only used by Mac OS implementation of Git.
	When core.precomposeunicode=true, Git reverts the unicode decomposition
243 244
	of filenames done by Mac OS. This is useful when sharing a repository
	between Mac OS and Linux or Windows.
245 246 247
	(Git for Windows 1.7.10 or higher is needed, or Git under cygwin 1.7).
	When false, file names are handled fully transparent by Git,
	which is backward compatible with older versions of Git.

249 250 251 252 253
	If set to true, do not allow checkout of paths that would
	be considered equivalent to `.git` on an HFS+ filesystem.
	Defaults to `true` on Mac OS, and `false` elsewhere.

254 255 256 257 258 259
	If set to true, do not allow checkout of paths that would
	cause problems with the NTFS filesystem, e.g. conflict with
	8.3 "short" names.
	Defaults to `true` on Windows, and `false` elsewhere.

260 261
	If false, the ctime differences between the index and the
	working tree are ignored; useful when the inode change time
263 264 265 266
	is regularly modified by something outside Git (file system
	crawlers and some backup systems).
	See linkgit:git-update-index[1]. True by default.

267 268 269 270 271 272
	Determines which stat fields to match between the index
	and work tree. The user can set this to 'default' or
	'minimal'. Default (or explicitly 'default'), is to check
	all fields, including the sub-second part of mtime and ctime.

274 275
	The commands that output paths (e.g. 'ls-files',
	'diff'), when not given the `-z` option, will quote
276 277 278 279 280 281 282 283 284
	"unusual" characters in the pathname by enclosing the
	pathname in a double-quote pair and with backslashes the
	same way strings in C source code are quoted.  If this
	variable is set to false, the bytes higher than 0x80 are
	not quoted but output as verbatim.  Note that double
	quote, backslash and control characters are always
	quoted without `-z` regardless of the setting of this

285 286 287 288 289 290 291
	Sets the line ending type to use in the working directory for
	files that have the `text` property set.  Alternatives are
	'lf', 'crlf' and 'native', which uses the platform's native
	line ending.  The default value is `native`.  See
	linkgit:gitattributes[5] for more information on end-of-line

	If true, makes Git check if converting `CRLF` is reversible when
	end-of-line conversion is active.  Git will verify if a command
296 297 298 299
	modifies a file in the work tree either directly or indirectly.
	For example, committing a file followed by checking out the
	same file should yield the original file in the work tree.  If
	this is not the case for the current setting of
300 301
	`core.autocrlf`, Git will reject the file.  The variable can
	be set to "warn", in which case Git will only warn about an
302 303 304
	irreversible conversion but continue the operation.
CRLF conversion bears a slight chance of corrupting data.
When it is enabled, Git will convert CRLF to LF during commit and LF to
CRLF during checkout.  A file that contains a mixture of LF and
CRLF before the commit cannot be recreated by Git.  For text
308 309 310 311 312 313 314 315 316
files this is the right thing to do: it corrects line endings
such that we have only LF line endings in the repository.
But for binary files that are accidentally classified as text the
conversion can corrupt data.
If you recognize such corruption early you can easily fix it by
setting the conversion type explicitly in .gitattributes.  Right
after committing you still have the original file in your work
tree and this file is not yet corrupted.  You can explicitly tell
Git that this file is binary and Git will handle the file
318 319 320 321 322 323 324 325 326 327 328
Unfortunately, the desired effect of cleaning up text files with
mixed line endings and the undesired effect of corrupting binary
files cannot be distinguished.  In both cases CRLFs are removed
in an irreversible way.  For text files this is the right thing
to do because CRLFs are line endings, while for binary files
converting CRLFs corrupts data.
Note, this safety check does not mean that a checkout will generate a
file identical to the original file for a different setting of
329 330 331
`core.eol` and `core.autocrlf`, but only for the current one.  For
example, a text file with `LF` would be accepted with `core.eol=lf`
and could later be checked out with `core.eol=crlf`, in which case the
332 333 334 335 336 337
resulting file would contain `CRLF`, although the original file
contained `LF`.  However, in both work trees the line endings would be
consistent, that is either all `LF` or all `CRLF`, but never mixed.  A
file with mixed line endings would be reported by the `core.safecrlf`

338 339 340 341 342 343 344 345 346 347
	Setting this variable to "true" is almost the same as setting
	the `text` attribute to "auto" on all files except that text
	files are not guaranteed to be normalized: files that contain
	`CRLF` in the repository will not be touched.  Use this
	setting if you want to have `CRLF` line endings in your
	working directory even though the repository does not have
	normalized line endings.  This variable can be set to 'input',
	in which case no output conversion is performed.

348 349
	If false, symbolic links are checked out as small plain files that
350 351
	contain the link text. linkgit:git-update-index[1] and
	linkgit:git-add[1] will not change the recorded type to regular
	file. Useful on filesystems like FAT that do not support
353 354 355 356 357
	symbolic links.
The default is true, except linkgit:git-clone[1] or linkgit:git-init[1]
will probe and set core.symlinks false if appropriate when the repository
is created.

359 360 361
	A "proxy command" to execute (as 'command host port') instead
	of establishing direct connection to the remote server when
	using the Git protocol for fetching. If the variable value is
363 364 365 366
	in the "COMMAND for DOMAIN" format, the command is applied only
	on hostnames ending with the specified domain string. This variable
	may be set multiple times and is matched in the given order;
	the first match wins.
367 368 369 370
Can be overridden by the 'GIT_PROXY_COMMAND' environment variable
(which always applies universally, without the special "for"
371 372 373 374 375
The special string `none` can be used as the proxy command to
specify that no proxy be used for a given domain pattern.
This is useful for excluding servers inside a firewall from
proxy use, while defaulting to a common proxy for external domains.
376 377

378 379 380
	If true, commands which modify both the working tree and the index
	will mark the updated paths with the "assume unchanged" bit in the
	index. These marked files are then assumed to stay unchanged in the
	working tree, until you mark them otherwise manually - Git will not
382 383 384
	detect the file changes	by lstat() calls. This is useful on systems
	where those are very slow, such as Microsoft Windows.
	See linkgit:git-update-index[1].
385 386
	False by default.

387 388 389 390 391
	Instead of the default "symref" format for HEAD
	and other symbolic reference files, use symbolic links.
	This is sometimes needed to work with old scripts that
	expect HEAD to be a symbolic link.

393 394 395 396
	If true this repository is assumed to be 'bare' and has no
	working directory associated with it.  If this is the case a
	number of commands that require a working directory will be
	disabled, such as linkgit:git-add[1] or linkgit:git-merge[1].
399 400
This setting is automatically guessed by linkgit:git-clone[1] or
linkgit:git-init[1] when the repository was created.  By default a
401 402 403 404
repository that ends in "/.git" is assumed to be not bare (bare =
false), while all other repositories are assumed to be bare (bare
= true).

	Set the path to the root of the working tree.
	This can be overridden by the GIT_WORK_TREE environment
	variable and the '--work-tree' command-line option.
	The value can be an absolute path or relative to the path to
410 411 412
	the .git directory, which is either specified by --git-dir
	or GIT_DIR, or automatically discovered.
	If --git-dir or GIT_DIR is specified but none of
	--work-tree, GIT_WORK_TREE and core.worktree is specified,
	the current working directory is regarded as the top level
	of your working tree.
416 417 418 419 420
Note that this variable is honored even when set in a configuration
file in a ".git" subdirectory of a directory and its value differs
from the latter directory (e.g. "/path/to/.git/config" has
core.worktree set to "/different/path"), which is most likely a
misconfiguration.  Running Git commands in the "/path/to" directory will
422 423 424 425
still use "/different/path" as the root of the work tree and can cause
confusion unless you know what you are doing (e.g. you are creating a
read-only snapshot of the same index to a location different from the
repository's usual working tree).

	Enable the reflog. Updates to a ref <ref> is logged to the file
	"$GIT_DIR/logs/<ref>", by appending the new and old
	SHA-1, the date/time and the reason of the update, but
431 432
	only when the file exists.  If this configuration
	variable is set to true, missing "$GIT_DIR/logs/<ref>"
433 434 435
	file is automatically created for branch heads (i.e. under
	refs/heads/), remote refs (i.e. under refs/remotes/),
	note refs (i.e. under refs/notes/), and the symbolic ref HEAD.
436 437 438 439 440 441 442
This information can be used to determine what commit
was the tip of a branch "2 days ago".
This value is true by default in a repository that has
a working directory associated with it, and false by
default in a bare repository.

444 445 446 447 448
	Internal variable identifying the repository format and layout

449 450 451 452
	When 'group' (or 'true'), the repository is made shareable between
	several users in a group (making sure all the files and objects are
	group-writable). When 'all' (or 'world' or 'everybody'), the
	repository will be readable by all users, additionally to being
	group-shareable. When 'umask' (or 'false'), Git will use permissions
454 455
	reported by umask(2). When '0xxx', where '0xxx' is an octal number,
	files in the repository will have this mode value. '0xxx' will override
456 457 458 459
	user's umask value (whereas the other options will only override
	requested parts of the user's umask value). Examples: '0660' will make
	the repo read/write-able for the owner and group, but inaccessible to
	others (equivalent to 'group' unless umask is e.g. '0022'). '0640' is a
460 461
	repository that is group-readable but not group-writable.
	See linkgit:git-init[1]. False by default.
462 463

	If true, Git will warn you if the ref name you passed it is ambiguous
Greg Price's avatar
Greg Price committed
	and might match multiple refs in the repository. True by default.

468 469 470
	An integer -1..9, indicating a default compression level.
	-1 is the zlib default. 0 means no compression,
	and 1..9 are various speed/size tradeoffs, 9 being slowest.
471 472
	If set, this provides a default to other compression variables,
	such as 'core.loosecompression' and 'pack.compression'.
473 474

	An integer -1..9, indicating the compression level for objects that
	are not in a pack file. -1 is the zlib default. 0 means no
	compression, and 1..9 are various speed/size tradeoffs, 9 being
	slowest.  If not set,  defaults to core.compression.  If that is
	not set,  defaults to 1 (best speed).

481 482 483 484 485
	Number of bytes of a pack file to map into memory in a
	single mapping operation.  Larger window sizes may allow
	your system to process a smaller number of large pack files
	more quickly.  Smaller window sizes will negatively affect
	performance due to increased calls to the operating system's
	memory manager, but may improve performance when accessing
488 489 490 491 492 493
	a large number of large pack files.
Default is 1 MiB if NO_MMAP was set at compile time, otherwise 32
MiB on 32 bit platforms and 1 GiB on 64 bit platforms.  This should
be reasonable for all users/operating systems.  You probably do
not need to adjust this value.
494 495
Common unit suffixes of 'k', 'm', or 'g' are supported.

497 498 499 500 501
	Maximum number of bytes to map simultaneously into memory
	from pack files.  If Git needs to access more than this many
	bytes at once to complete an operation it will unmap existing
	regions to reclaim virtual address space within the process.
502 503 504 505
Default is 256 MiB on 32 bit platforms and 8 GiB on 64 bit platforms.
This should be reasonable for all users/operating systems, except on
the largest projects.  You probably do not need to adjust this value.
506 507
Common unit suffixes of 'k', 'm', or 'g' are supported.

509 510
	Maximum number of bytes to reserve for caching base objects
	that may be referenced by multiple deltified objects.  By storing the
512 513 514 515
	entire decompressed base objects in a cache Git is able
	to avoid unpacking and decompressing frequently used base
	objects multiple times.
Default is 96 MiB on all platforms.  This should be reasonable
517 518 519 520 521
for all users/operating systems, except on the largest projects.
You probably do not need to adjust this value.
Common unit suffixes of 'k', 'm', or 'g' are supported.

522 523 524 525
	Files larger than this size are stored deflated, without
	attempting delta compression.  Storing large files without
	delta compression avoids excessive memory usage, at the
526 527
	slight expense of increased disk usage. Additionally files
	larger than this size are always treated as binary.
528 529 530 531 532 533 534
Default is 512 MiB on all platforms.  This should be reasonable
for most projects as source code and other text files can still
be delta compressed, but larger binary media files won't be.
Common unit suffixes of 'k', 'm', or 'g' are supported.

	In addition to '.gitignore' (per-directory) and
	'.git/info/exclude', Git looks into this file for patterns
538 539
	of files which are not meant to be tracked.  "`~/`" is expanded
	to the value of `$HOME` and "`~user/`" to the specified user's
540 541 542
	home directory. Its default value is $XDG_CONFIG_HOME/git/ignore.
	If $XDG_CONFIG_HOME is either not set or empty, $HOME/.config/git/ignore
	is used instead. See linkgit:gitignore[5].

544 545 546
	Some commands (e.g. svn and http interfaces) that interactively
	ask for a password can be told to use an external program given
547 548 549 550
	via the value of this variable. Can be overridden by the 'GIT_ASKPASS'
	environment variable. If not set, fall back to the value of the
	'SSH_ASKPASS' environment variable or, failing that, a simple password
	prompt. The external program shall be given a suitable prompt as
	command-line argument and write the password on its STDOUT.

553 554
	In addition to '.gitattributes' (per-directory) and
	'.git/info/attributes', Git looks into this file for attributes
	(see linkgit:gitattributes[5]). Path expansions are made the same
557 558 559
	way as for `core.excludesfile`. Its default value is
	$XDG_CONFIG_HOME/git/attributes. If $XDG_CONFIG_HOME is either not
	set or empty, $HOME/.config/git/attributes is used instead.

561 562
	Commands such as `commit` and `tag` that lets you edit
	messages by launching an editor uses the value of this
	variable when it is set, and the environment variable
	`GIT_EDITOR` is not set.  See linkgit:git-var[1].

Junio C Hamano's avatar
Junio C Hamano committed
567 568 569 570 571
	Commands such as `commit` and `tag` that lets you edit
	messages consider a line that begins with this character
	commented, and removes them after the editor returns
	(default '#').
572 573 574
If set to "auto", `git-commit` would select a character that is not
the beginning character of any line in existing commit messages.
Junio C Hamano's avatar
Junio C Hamano committed

	Text editor used by `git rebase -i` for editing the rebase instruction file.
578 579 580 581
	The value is meant to be interpreted by the shell when it is used.
	It can be overridden by the `GIT_SEQUENCE_EDITOR` environment variable.
	When not configured the default commit message editor is used instead.

583 584 585 586 587 588
	Text viewer for use by Git commands (e.g., 'less').  The value
	is meant to be interpreted by the shell.  The order of preference
	is the `$GIT_PAGER` environment variable, then `core.pager`
	configuration, then `$PAGER`, and then the default chosen at
	compile time (usually 'less').
When the `LESS` environment variable is unset, Git sets it to `FRX`
590 591
(if `LESS` environment variable is set, Git does not change it at
all).  If you want to selectively override Git's default setting
for `LESS`, you can set `core.pager` to e.g. `less -S`.  This will
be passed to the shell by Git, which will translate the final
594 595 596 597 598 599 600 601
command to `LESS=FRX less -S`. The environment does not set the
`S` option but the command line does, instructing less to truncate
long lines. Similarly, setting `core.pager` to `less -+F` will
deactivate the `F` option specified by the environment from the
command-line, deactivating the "quit if one screen" behavior of
`less`.  One can specifically activate some flags for particular
commands: for example, setting `pager.blame` to `less -S` enables
line truncation only for `git blame`.
602 603 604 605
Likewise, when the `LV` environment variable is unset, Git sets it
to `-c`.  You can override this setting by exporting `LV` with
another value or setting `core.pager` to `lv +c`.

607 608
	A comma separated list of common whitespace problems to
609 610
	notice.  'git diff' will use `color.diff.whitespace` to
	highlight them, and 'git apply --whitespace=error' will
611 612
	consider them as errors.  You can prefix `-` to disable
	any of them (e.g. `-trailing-space`):
* `blank-at-eol` treats trailing whitespaces at the end of the line
615 616 617 618
  as an error (enabled by default).
* `space-before-tab` treats a space character that appears immediately
  before a tab character in the initial indent part of the line as an
  error (enabled by default).
619 620 621
* `indent-with-non-tab` treats a line that is indented with space
  characters instead of the equivalent tabs as an error (not enabled by
622 623
* `tab-in-indent` treats a tab character in the initial indent part of
  the line as an error (not enabled by default).
624 625
* `blank-at-eof` treats blank lines added at the end of file as an error
  (enabled by default).
626 627
* `trailing-space` is a short-hand to cover both `blank-at-eol` and
Junio C Hamano's avatar
Junio C Hamano committed
628 629 630 631
* `cr-at-eol` treats a carriage-return at the end of line as
  part of the line terminator, i.e. with it, `trailing-space`
  does not trigger if the character before such a carriage-return
  is not a whitespace (not enabled by default).
* `tabwidth=<n>` tells how many character positions a tab occupies; this
  is relevant for `indent-with-non-tab` and when Git fixes `tab-in-indent`
  errors. The default tab width is 8. Allowed values are 1 to 63.

636 637 638 639 640 641 642 643
	This boolean will enable 'fsync()' when writing object files.
This is a total waste of time and effort on a filesystem that orders
data writes properly, but can be useful for filesystems that do not use
journalling (traditional UNIX filesystems) or that only journal metadata
and not file contents (OS X's HFS+, or Linux ext3 with "data=writeback").

Linus Torvalds's avatar
Linus Torvalds committed
644 645 646 647 648
	Enable parallel index preload for operations like 'git diff'
This can speed up operations like 'git diff' and 'git status' especially
on filesystems like NFS that have weak caching semantics and thus
relatively high IO latencies.  When enabled, Git will do the
Linus Torvalds's avatar
Linus Torvalds committed
index comparison to the filesystem data in parallel, allowing
overlapping IO's.  Defaults to true.
Linus Torvalds's avatar
Linus Torvalds committed

653 654 655 656 657 658 659 660
	You can set this to 'link', in which case a hardlink followed by
	a delete of the source are used to make sure that object creation
	will not overwrite existing objects.
On some file system/operating system combinations, this is unreliable.
Set this config setting to 'rename' there; However, This will remove the
check that makes sure that existing object files will not get overwritten.

Johannes Schindelin's avatar
Johannes Schindelin committed
662 663
	When showing commit messages, also show notes which are stored in
664 665 666
	the given ref.  The ref must be fully qualified.  If the given
	ref does not exist, it is not an error but means that no
	notes should be printed.
Johannes Schindelin's avatar
Johannes Schindelin committed
668 669
This setting defaults to "refs/notes/commits", and it can be overridden by
the 'GIT_NOTES_REF' environment variable.  See linkgit:git-notes[1].
Johannes Schindelin's avatar
Johannes Schindelin committed

671 672 673 674
	Enable "sparse checkout" feature. See section "Sparse checkout" in
	linkgit:git-read-tree[1] for more information.

676 677 678 679 680
	Set the length object names are abbreviated to.  If unspecified,
	many commands abbreviate to 7 hexdigits, which may not be enough
	for abbreviated object names to stay unique for sufficiently long

	Tells 'git add' to continue adding files when some files cannot be
	added due to indexing errors. Equivalent to the '--ignore-errors'
	option of linkgit:git-add[1].  Older versions of Git accept only
	`add.ignore-errors`, which does not follow the usual naming
	convention for configuration variables.  Newer versions of Git
	honor `add.ignoreErrors` as well.

Petr Baudis's avatar
Petr Baudis committed
	Command aliases for the linkgit:git[1] command wrapper - e.g.
Petr Baudis's avatar
Petr Baudis committed
692 693
	after defining "alias.last = cat-file commit HEAD", the invocation
	"git last" is equivalent to "git cat-file commit HEAD". To avoid
Petr Baudis's avatar
Petr Baudis committed
	confusion and troubles with script usage, aliases that
	hide existing Git commands are ignored. Arguments are split by
Petr Baudis's avatar
Petr Baudis committed
	spaces, the usual shell quoting and escaping is supported.
	A quote pair or a backslash can be used to quote them.
698 699 700 701 702
If the alias expansion is prefixed with an exclamation point,
it will be treated as a shell command.  For example, defining
" = !gitk --all --not ORIG_HEAD", the invocation
"git new" is equivalent to running the shell command
703 704 705
"gitk --all --not ORIG_HEAD".  Note that shell commands will be
executed from the top-level directory of a repository, which may
not necessarily be the current directory.
706 707
'GIT_PREFIX' is set as returned by running 'git rev-parse --show-prefix'
from the original current directory. See linkgit:git-rev-parse[1].

709 710 711
	If true, git-am will call git-mailsplit for patches in mbox format
	with parameter '--keep-cr'. In this case git-mailsplit will
	not remove `\r` from lines ending with `\r\n`. Can be overridden
713 714 715
	by giving '--no-keep-cr' from the command line.
	See linkgit:git-am[1], linkgit:git-mailsplit[1].

	When set to 'change', tells 'git apply' to ignore changes in
718 719
	whitespace, in the same way as the '--ignore-space-change'
	When set to one of: no, none, never, false tells 'git apply' to
721 722 723
	respect all whitespace differences.
	See linkgit:git-apply[1].

	Tells 'git apply' how to handle whitespaces, in the same way
	as the '--whitespace' option. See linkgit:git-apply[1].

	Tells 'git branch' and 'git checkout' to set up new branches
730 731
	so that linkgit:git-pull[1] will appropriately merge from the
	starting point branch. Note that even if this option is not set,
	this behavior can be chosen per-branch using the `--track`
733 734
	and `--no-track` options. The valid settings are: `false` -- no
	automatic setup is done; `true` -- automatic setup is done when the
735 736 737
	starting point is a remote-tracking branch; `always` --
	automatic setup is done when the starting point is either a
	local branch or remote-tracking
	branch. This option defaults to true.

	When a new branch is created with 'git branch' or 'git checkout'
	that tracks another branch, this variable tells Git to set
743 744 745 746 747
	up pull to rebase instead of merge (see "branch.<name>.rebase").
	When `never`, rebase is never automatically set to true.
	When `local`, rebase is set to true for tracked branches of
	other local branches.
	When `remote`, rebase is set to true for tracked branches of
	remote-tracking branches.
749 750 751 752 753 754
	When `always`, rebase will be set to true for all tracking
	See "branch.autosetupmerge" for details on how to set up a
	branch to track another branch.
	This option defaults to never.

756 757 758
	When on branch <name>, it tells 'git fetch' and 'git push'
	which remote to fetch from/push to.  The remote to push to
	may be overridden with `remote.pushdefault` (for all branches).
759 760 761 762
	The remote to push to, for the current branch, may be further
	overridden by `branch.<name>.pushremote`.  If no remote is
	configured, or if you are not on any branch, it defaults to
	`origin` for fetching and `remote.pushdefault` for pushing.
763 764
	Additionally, `.` (a period) is the current local repository
	(a dot-repository), see `branch.<name>.merge`'s final note below.
765 766 767 768 769 770 771 772 773

	When on branch <name>, it overrides `branch.<name>.remote` for
	pushing.  It also overrides `remote.pushdefault` for pushing
	from branch <name>.  When you pull from one place (e.g. your
	upstream) and push to another place (e.g. your own publishing
	repository), you would want to set `remote.pushdefault` to
	specify the remote to push to for all branches, and use this
	option to override it for a specific branch.

	Defines, together with branch.<name>.remote, the upstream branch
	for the given branch. It tells 'git fetch'/'git pull'/'git rebase' which
778 779
	branch to merge and can also affect 'git push' (see push.default).
	When in branch <name>, it tells 'git fetch' the default
Daniel Barkalow's avatar
Daniel Barkalow committed
780 781 782 783
	refspec to be marked for merging in FETCH_HEAD. The value is
	handled like the remote part of a refspec, and must match a
	ref which is fetched from the remote given by
784 785 786
	The merge information is used by 'git pull' (which at first calls
	'git fetch') to lookup the default branch for merging. Without
	this option, 'git pull' defaults to merge the first refspec fetched.
	Specify multiple values to get an octopus merge.
	If you wish to setup 'git pull' so that it merges into <name> from
	another branch in the local repository, you can point
790 791
	branch.<name>.merge to the desired branch, and use the relative path
	setting `.` (a period) for branch.<name>.remote.

793 794
	Sets default options for merging into branch <name>. The syntax and
	supported options are the same as those of linkgit:git-merge[1], but
796 797 798
	option values containing whitespace characters are currently not

799 800
	When true, rebase the branch <name> on top of the fetched branch,
	instead of merging the default branch from the default remote when
802 803
	"git pull" is run. See "pull.rebase" for doing this in a non
	branch-specific manner.
804 805 806 807
	When preserve, also pass `--preserve-merges` along to 'git rebase'
	so that locally committed merge commits will not be flattened
	by running 'git pull'.
808 809 810 811
*NOTE*: this is a possibly dangerous operation; do *not* use
it unless you understand the implications (see linkgit:git-rebase[1]
for details).

813 814 815 816 817 818
	Branch description, can be edited with
	`git branch --edit-description`. Branch description is
	automatically added in the format-patch cover letter or
	request-pull summary.

819 820 821
	Specify the command to invoke the specified browser. The
	specified command is evaluated in shell with the URLs passed
	as arguments. (See linkgit:git-web{litdd}browse[1].)

824 825
	Override the path for the given tool that may be used to
826 827
	browse HTML help (see '-w' option in linkgit:git-help[1]) or a
	working repository in gitweb (see linkgit:git-instaweb[1]).

830 831
	A boolean to make git-clean do nothing unless given -f,
	-i or -n.   Defaults to true.

833 834
	A boolean to enable/disable color in the output of
	linkgit:git-branch[1]. May be set to `always`,
	`false` (or `never`) or `auto` (or `true`), in which case colors are used
837 838 839 840 841
	only when the output is to a terminal. Defaults to false.

	Use customized color for branch coloration. `<slot>` is one of
	`current` (the current branch), `local` (a local branch),
842 843
	`remote` (a remote-tracking branch in refs/remotes/),
	`upstream` (upstream tracking branch), `plain` (other
844 845 846 847 848 849 850 851 852
The value for these configuration variables is a list of colors (at most
two) and attributes (at most one), separated by spaces.  The colors
accepted are `normal`, `black`, `red`, `green`, `yellow`, `blue`,
`magenta`, `cyan` and `white`; the attributes are `bold`, `dim`, `ul`,
`blink` and `reverse`.  The first color given is the foreground; the
second is the background.  The position of the attribute, if any,
doesn't matter.
853 854 855 856
Colors (foreground and background) may also be given as numbers between
0 and 255; these use ANSI 256-color mode (but note that not all
terminals may support this).

859 860 861 862 863 864 865
	Whether to use ANSI escape sequences to add color to patches.
	If this is set to `always`, linkgit:git-diff[1],
	linkgit:git-log[1], and linkgit:git-show[1] will use color
	for all patches.  If it is set to `true` or `auto`, those
	commands will only use color when output is to the terminal.
	Defaults to false.
This does not affect linkgit:git-format-patch[1] or the
867 868
'git-diff-{asterisk}' plumbing commands.  Can be overridden on the
command line with the `--color[=<when>]` option.

871 872 873
	Use customized color for diff colorization.  `<slot>` specifies
	which part of the patch to use the specified color, and is one
	of `plain` (context text), `meta` (metainformation), `frag`
874 875 876 877
	(hunk header), 'func' (function in hunk header), `old` (removed lines),
	`new` (added lines), `commit` (commit headers), or `whitespace`
	(highlighting whitespace errors). The values of these variables may be
	specified as in color.branch.<slot>.

879 880 881
	Use customized color for 'git log --decorate' output.  `<slot>` is one
	of `branch`, `remoteBranch`, `tag`, `stash` or `HEAD` for local
	branches, remote-tracking branches, tags, stash and HEAD, respectively.

884 885 886 887 888
	When set to `always`, always highlight matches.  When `false` (or
	`never`), never.  When set to `true` or `auto`, use color only
	when the output is written to the terminal.  Defaults to `false`.

889 890 891 892 893
	Use customized color for grep colorization.  `<slot>` specifies which
	part of the line to use the specified color, and is one of
894 895
	non-matching text in context lines (when using `-A`, `-B`, or `-C`)
896 897
	filename prefix (when not using `-h`)
898 899
	function name lines (when using `-p`)
900 901 902
	line number prefix (when using `-n`)
903 904 905 906 907
	matching text (same as setting `matchContext` and `matchSelected`)
	matching text in context lines
	matching text in selected lines
908 909
	non-matching text in selected lines
910 911 912 913 914 915
	separators between fields on a line (`:`, `-`, and `=`)
	and between hunks (`--`)
The values of these variables may be specified as in color.branch.<slot>.

	When set to `always`, always use colors for interactive prompts
919 920 921 922
	and displays (such as those used by "git-add --interactive" and
	"git-clean --interactive"). When false (or `never`), never.
	When set to `true` or `auto`, use colors only when the output is
	to the terminal. Defaults to false.
923 924

925 926 927 928 929
	Use customized color for 'git add --interactive' and 'git clean
	--interactive' output. `<slot>` may be `prompt`, `header`, `help`
	or `error`, for four distinct types of normal output from
	interactive commands.  The values of these variables may be
	specified as in color.branch.<slot>.

931 932 933 934
	A boolean to enable/disable colored output when the pager is in
	use (default is true).

935 936 937 938 939 940
	A boolean to enable/disable color in the output of
	linkgit:git-show-branch[1]. May be set to `always`,
	`false` (or `never`) or `auto` (or `true`), in which case colors are used
	only when the output is to a terminal. Defaults to false.

941 942
	A boolean to enable/disable color in the output of
	linkgit:git-status[1]. May be set to `always`,
	`false` (or `never`) or `auto` (or `true`), in which case colors are used
945 946 947 948 949
	only when the output is to a terminal. Defaults to false.

	Use customized color for status colorization. `<slot>` is
	one of `header` (the header text of the status message),
950 951
	`added` or `updated` (files which are added but not committed),
	`changed` (files which are changed but not added in the index),
	`untracked` (files which are not tracked by Git),
	`branch` (the current branch), or
954 955 956
	`nobranch` (the color the 'no branch' warning is shown in, defaulting
	to red). The values of these variables may be specified as in

959 960 961 962
	This variable determines the default value for variables such
	as `color.diff` and `color.grep` that control the use of color
	per command family. Its scope will expand as more commands learn
	configuration to set a default for the `--color` option.  Set it
963 964 965 966 967 968
	to `false` or `never` if you prefer Git commands not to use
	color unless enabled explicitly with some other configuration
	or the `--color` option. Set it to `always` if you want all
	output not intended for machine consumption to use color, to
	`true` or `auto` (this is the default since Git 1.8.4) if you
	want such output to use color when written to the terminal.

970 971 972 973 974
	Specify whether supported commands should output in columns.
	This variable consists of a list of tokens separated by spaces
	or commas:
975 976 977
These options control when the feature should be enabled
(defaults to 'never'):
978 979 980 981 982 983 984
	always show in columns
	never show in columns
	show in columns if the output is to the terminal
985 986 987 988 989 990 991
These options control layout (defaults to 'column').  Setting any
of these implies 'always' if none of 'always', 'never', or 'auto' are
Duy Nguyen's avatar
Duy Nguyen committed
	fill columns before rows
Duy Nguyen's avatar
Duy Nguyen committed
994 995
	fill rows before columns
996 997
	show in one column
998 999 1000 1001 1002 1003
Finally, these options can be combined with a layout option (defaults
to 'nodense'):
1004 1005 1006 1007
	make unequal size columns to utilize more space
	make equal size columns
1008 1009

Duy Nguyen's avatar
Duy Nguyen committed
1010 1011 1012 1013
	Specify whether to output branch listing in `git branch` in columns.
	See `column.ui` for details.

1014 1015 1016 1017
	Specify the layout when list items in `git clean -i`, which always
	shows files and directories in columns. See `column.ui` for details.

Duy Nguyen's avatar
Duy Nguyen committed
1018 1019 1020 1021
	Specify whether to output untracked files in `git status` in columns.
	See `column.ui` for details.

Duy Nguyen's avatar
Duy Nguyen committed
1022 1023 1024 1025
	Specify whether to output tag listing in `git tag` in columns.
	See `column.ui` for details.

1026 1027 1028 1029 1030 1031 1032 1033 1034
	This setting overrides the default of the `--cleanup` option in
	`git commit`. See linkgit:git-commit[1] for details. Changing the
	default can be useful when you always want to keep lines that begin
	with comment character `#` in your log message, in which case you
	would do `git config commit.cleanup whitespace` (note that you will
	have to remove the help lines that begin with `#` in the commit log
	template yourself, if you do this).

1035 1036 1037 1038 1039 1040 1041 1042

	A boolean to specify whether all commits should be GPG signed.
	Use of this option when doing operations such as rebase can
	result in a large number of commits being signed. It may be
	convenient to use an agent to avoid typing your GPG passphrase
	several times.

1044 1045 1046 1047
	A boolean to enable/disable inclusion of status information in the
	commit message template when using an editor to prepare the commit
	message.  Defaults to true.

1048 1049
	Specify a file to use as the template for new commit messages.
	"`~/`" is expanded to the value of `$HOME` and "`~user/`" to the
	specified user's home directory.

1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075
	Specify an external helper to be called when a username or
	password credential is needed; the helper may consult external
	storage to avoid prompting the user for the credentials. See
	linkgit:gitcredentials[7] for details.

	When acquiring credentials, consider the "path" component of an http
	or https URL to be important. Defaults to false. See
	linkgit:gitcredentials[7] for more information.

	If no username is set for a network authentication, use this username
	by default. See credential.<context>.* below, and

	Any of the credential.* options above can be applied selectively to
	some credentials. For example "credential."
	would set the default username only for https connections to See linkgit:gitcredentials[7] for details on how URLs are

1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089

	Override the path for the given tool.  This is useful in case
	your tool is not in the PATH.

	Specify the command to invoke the specified diff tool.
	The specified command is evaluated in shell with the following
	variables available:  'LOCAL' is set to the name of the temporary
	file containing the contents of the diff pre-image and 'REMOTE'
	is set to the name of the temporary file containing the contents
	of the diff post-image.

1090 1091 1092
	Prompt before each invocation of the diff tool.

1094 1095 1096 1097 1098 1099 1100
	This option can be either set to a boolean value or to 'on-demand'.
	Setting it to a boolean changes the behavior of fetch and pull to
	unconditionally recurse into submodules when set to true or to not
	recurse at all when set to false. When set to 'on-demand' (the default
	value), fetch and pull will only recurse into a populated submodule
	when its superproject retrieves a commit that updates the submodule's

1102 1103 1104 1105
	If it is set to true, git-fetch-pack will check all fetched
	objects. It will abort in the case of a malformed object or a
	broken link. The result of an abort are only dangling objects.
1106 1107
	Defaults to false. If not set, the value of `transfer.fsckObjects`
	is used instead.

	If the number of objects fetched over the Git native
1111 1112 1113 1114 1115 1116
	transfer is below this
	limit, then the objects will be unpacked into loose object
	files. However if the number of received objects equals or
	exceeds this limit then the received pack will be stored as
	a pack, after adding any missing delta bases.  Storing the
	pack from a push can make the push operation complete faster,
1117 1118
	especially on slow filesystems.  If not set, the value of
	`transfer.unpackLimit` is used instead.

1120 1121 1122 1123
	If true, fetch will automatically behave as if the `--prune`
	option was given on the command line.  See also `remote.<name>.prune`.

1124 1125 1126 1127 1128 1129 1130
	Enable multipart/mixed attachments as the default for
	'format-patch'.  The value can also be a double quoted string
	which will enable attachments as the default and set the
	value as the boundary.  See the --attach option in

1132 1133 1134 1135 1136
	A boolean which can enable or disable sequence numbers in patch
	subjects.  It defaults to "auto" which enables it only if there
	is more than one patch.  It can be enabled or disabled for all
	messages by setting it to "true" or "false".  See --numbered
	option in linkgit:git-format-patch[1].

1138 1139
	Additional email headers to include in a patch to be submitted
	by mail.  See linkgit:git-format-patch[1].

1144 1145 1146
	Additional recipients to include in a patch to be submitted
	by mail.  See the --to and --cc options in
1147 1148 1149 1150 1151

	The default for format-patch is to output files with the '[PATCH]'
	subject prefix. Use this variable to change that prefix.

1152 1153
	The default for format-patch is to output a signature containing
	the Git version number. Use this variable to change that default.
1155 1156 1157
	Set this variable to the empty string ("") to suppress
	signature generation.

1158 1159 1160 1161
	Works just like format.signature except the contents of the
	file specified by this variable will be used as the signature.

1162 1163 1164 1165
	The default for format-patch is to output files with the suffix
	`.patch`. Use this variable to change that suffix (make sure to
	include the dot if you want it).