dot-separated segment and the section name is everything before the last
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.
+variables may appear multiple times; we say then that the variable is
+multivalued.
Syntax
~~~~~~
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
+section begins. Section names are case-insensitive. Only alphanumeric
characters, `-` and `.` are allowed in section names. Each variable
must belong to some section, which means that there must be a section
header before the first setting of a variable.
--------
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
+newline (doublequote `"` and backslash can be included by escaping them
+as `\"` and `\\`, respectively). Section headers cannot span multiple
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.
All the other lines (and the remainder of the line after the section
header) are recognized as setting variables, in the form
-'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".
+'name = value' (or just 'name', which is a short-hand to say that
+the variable is the boolean "true").
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
-multivalued.
-
-Leading and trailing whitespace in a variable value is discarded.
-Internal whitespace within a variable value is retained verbatim.
+and `-`, and must start with an alphabetic character.
-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".
+A line that defines a value can be continued to the next line by
+ending it with a `\`; the backquote and the end-of-line are
+stripped. Leading whitespaces after 'name =', the remainder of the
+line after the first comment character '#' or ';', and trailing
+whitespaces of the line are discarded unless they are enclosed in
+double quotes. Internal whitespaces within the value are retained
+verbatim.
-String values may be entirely or partially enclosed in double quotes.
-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 `\`.
+Inside double quotes, double quote `"` and backslash `\` characters
+must be escaped: use `\"` for `"` and `\\` for `\`.
The following escape sequences (beside `\"` and `\\`) are recognized:
`\n` for newline character (NL), `\t` for horizontal tabulation (HT, TAB)
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
-customary UNIX fashion.
-
-Some variables may require a special value format.
Includes
~~~~~~~~
path = foo ; expand "foo" relative to the current file
path = ~/foo ; expand "foo" in your $HOME directory
+
+Values
+~~~~~~
+
+Values of many variables are treated as a simple string, but there
+are variables that take values of specific types and there are rules
+as to how to spell them.
+
+boolean::
+
+ When a variable is said to take a boolean value, many
+ synonyms are accepted for 'true' and 'false'; these are all
+ case-insensitive.
+
+ true;; Boolean true can be spelled as `yes`, `on`, `true`,
+ or `1`. Also, a variable defined without `= <value>`
+ is taken as true.
+
+ false;; Boolean false can be spelled as `no`, `off`,
+ `false`, or `0`.
++
+When converting value to the canonical form using '--bool' type
+specifier; 'git config' will ensure that the output is "true" or
+"false" (spelled in lowercase).
+
+integer::
+ The value for many variables that specify various sizes can
+ be suffixed with `k`, `M`,... to mean "scale the number by
+ 1024", "by 1024x1024", etc.
+
+color::
+ The value for a variables that takes a color 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. Attributes may be turned off specifically
+ by prefixing them with `no` (e.g., `noreverse`, `noul`, etc).
++
+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). If your terminal supports it, you may also
+specify 24-bit RGB values as hex, like `#ff0ab3`.
++
+The attributes are meant to be reset at the beginning of each item
+in the colored output, so setting color.decorate.branch to `black`
+will paint that branch name in a plain `black`, even if the previous
+thing on the same output line (e.g. opening parenthesis before the
+list of branch names in `log --decorate` output) is set to be
+painted with `bold` or some other attribute.
+
+
Variables
~~~~~~~~~
core.worktree::
Set the path to the root of the working tree.
+ If GIT_COMMON_DIR environment variable is set, core.worktree
+ is ignored and not used for determining the root of 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
If set to "auto", `git-commit` would select a character that is not
the beginning character of any line in existing commit messages.
+core.packedRefsTimeout::
+ The length of time, in milliseconds, to retry when trying to
+ lock the `packed-refs` file. Value 0 means not to retry at
+ all; -1 means to try indefinitely. Default is 1000 (i.e.,
+ retry for 1 second).
+
sequence.editor::
Text editor used by `git rebase -i` for editing the rebase instruction file.
The value is meant to be interpreted by the shell when it is used.
by giving '--no-keep-cr' from the command line.
See linkgit:git-am[1], linkgit:git-mailsplit[1].
+am.threeWay::
+ By default, `git am` will fail if the patch does not apply cleanly. When
+ set to true, this setting tells `git am` to fall back on 3-way merge if
+ the patch records the identity of blobs it is supposed to apply to and
+ we have those blobs available locally (equivalent to giving the `--3way`
+ option from the command line). Defaults to `false`.
+ See linkgit:git-am[1].
+
apply.ignoreWhitespace::
When set to 'change', tells 'git apply' to ignore changes in
whitespace, in the same way as the '--ignore-space-change'
`remote` (a remote-tracking branch in refs/remotes/),
`upstream` (upstream tracking branch), `plain` (other
refs).
-+
-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. Attributes may be turned off specifically by prefixing
-them with `no` (e.g., `noreverse`, `noul`, etc).
-+
-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). If your terminal supports it, you may also
-specify 24-bit RGB values as hex, like `#ff0ab3`.
color.diff::
Whether to use ANSI escape sequences to add color to patches.
color.diff.<slot>::
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`
+ of `context` (context text - `plain` is a historical synonym),
+ `meta` (metainformation), `frag`
(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>.
+ (highlighting whitespace errors).
color.decorate.<slot>::
Use customized color for 'git log --decorate' output. `<slot>` is one
separators between fields on a line (`:`, `-`, and `=`)
and between hunks (`--`)
--
-+
-The values of these variables may be specified as in color.branch.<slot>.
color.interactive::
When set to `always`, always use colors for interactive prompts
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>.
+ interactive commands.
color.pager::
A boolean to enable/disable colored output when the pager is in
`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
+ `branch` (the current branch),
`nobranch` (the color the 'no branch' warning is shown in, defaulting
- to red). The values of these variables may be specified as in
- color.branch.<slot>.
+ to red), or
+ `unmerged` (files which have unmerged changes).
color.ui::
This variable determines the default value for variables such
object to a worktree file upon checkout. See
linkgit:gitattributes[5] for details.
+fsck.<msg-id>::
+ Allows overriding the message type (error, warn or ignore) of a
+ specific message ID such as `missingEmail`.
++
+For convenience, fsck prefixes the error/warning with the message ID,
+e.g. "missingEmail: invalid author/committer line - missing email" means
+that setting `fsck.missingEmail = ignore` will hide that issue.
++
+This feature is intended to support working with legacy repositories
+which cannot be repaired without disruptive changes.
+
+fsck.skipList::
+ The path to a sorted list of object names (i.e. one SHA-1 per
+ line) that are known to be broken in a non-fatal way and should
+ be ignored. This feature is useful when an established project
+ should be accepted despite early commits containing errors that
+ can be safely ignored such as invalid committer email addresses.
+ Note: corrupt objects cannot be skipped with this setting.
+
gc.aggressiveDepth::
The depth parameter used in the delta compression
algorithm used by 'git gc --aggressive'. This defaults
gc.pruneExpire::
When 'git gc' is run, it will call 'prune --expire 2.weeks.ago'.
Override the grace period with this config variable. The value
- "now" may be used to disable this grace period and always prune
- unreachable objects immediately.
+ "now" may be used to disable this grace period and always prune
+ unreachable objects immediately, or "never" may be used to
+ suppress pruning.
+
+gc.worktreePruneExpire::
+ When 'git gc' is run, it calls
+ 'git worktree prune --expire 3.months.ago'.
+ This config variable can be used to set a different grace
+ period. The value "now" may be used to disable the grace
+ period and prune $GIT_DIR/worktrees immediately, or "never"
+ may be used to suppress pruning.
gc.reflogExpire::
gc.<pattern>.reflogExpire::
'git reflog expire' removes reflog entries older than
- this time; defaults to 90 days. With "<pattern>" (e.g.
+ this time; defaults to 90 days. The value "now" expires all
+ entries immediately, and "never" suppresses expiration
+ altogether. With "<pattern>" (e.g.
"refs/stash") in the middle the setting applies only to
the refs that match the <pattern>.
gc.reflogExpireUnreachable::
- gc.<ref>.reflogExpireUnreachable::
+ gc.<pattern>.reflogExpireUnreachable::
'git reflog expire' removes reflog entries older than
this time and are not reachable from the current tip;
- defaults to 30 days. With "<pattern>" (e.g. "refs/stash")
+ defaults to 30 days. The value "now" expires all entries
+ immediately, and "never" suppresses expiration altogether.
+ With "<pattern>" (e.g. "refs/stash")
in the middle, the setting applies only to the refs that
match the <pattern>.
If set, store cookies received during requests to the file specified by
http.cookieFile. Has no effect if http.cookieFile is unset.
+http.sslVersion::
+ The SSL version to use when negotiating an SSL connection, if you
+ want to force the default. The available and default version
+ depend on whether libcurl was built against NSS or OpenSSL and the
+ particular configuration of the crypto library in use. Internally
+ this sets the 'CURLOPT_SSL_VERSION' option; see the libcurl
+ documentation for more details on the format of this option and
+ for the ssl version supported. Actually the possible values of
+ this option are:
+
+ - sslv2
+ - sslv3
+ - tlsv1
+ - tlsv1.0
+ - tlsv1.1
+ - tlsv1.2
+
++
+Can be overridden by the 'GIT_SSL_VERSION' environment variable.
+To force git to use libcurl's default ssl version and ignore any
+explicit http.sslversion option, set 'GIT_SSL_VERSION' to the
+empty string.
+
+http.sslCipherList::
+ A list of SSL ciphers to use when negotiating an SSL connection.
+ The available ciphers depend on whether libcurl was built against
+ NSS or OpenSSL and the particular configuration of the crypto
+ library in use. Internally this sets the 'CURLOPT_SSL_CIPHER_LIST'
+ option; see the libcurl documentation for more details on the format
+ of this list.
++
+Can be overridden by the 'GIT_SSL_CIPHER_LIST' environment variable.
+To force git to use libcurl's default cipher list and ignore any
+explicit http.sslCipherList option, set 'GIT_SSL_CIPHER_LIST' to the
+empty string.
+
http.sslVerify::
Whether to verify the SSL certificate when fetching or pushing
over HTTPS. Can be overridden by the 'GIT_SSL_NO_VERIFY' environment
a case (equivalent to giving the `--no-ff` option from the command
line). When set to `only`, only such fast-forward merges are
allowed (equivalent to giving the `--ff-only` option from the
- command line).
+ command line). This setting overrides `merge.ff` when pulling.
pull.rebase::
When true, rebase branches on top of the fetched branch, instead
--
+push.followTags::
+ If set to true enable '--follow-tags' option by default. You
+ may override this configuration at time of push by specifying
+ '--no-follow-tags'.
+
+
rebase.stat::
Whether to show a diffstat of what changed upstream since the last
rebase. False by default.
successful rebase might result in non-trivial conflicts.
Defaults to false.
+rebase.missingCommitsCheck::
+ If set to "warn", git rebase -i will print a warning if some
+ commits are removed (e.g. a line was deleted), however the
+ rebase will still proceed. If set to "error", it will print
+ the previous warning and stop the rebase, 'git rebase
+ --edit-todo' can then be used to correct the error. If set to
+ "ignore", no checking is done.
+ To drop a commit without warning or error, use the `drop`
+ command in the todo-list.
+ Defaults to "ignore".
+
+rebase.instructionFormat
+ A format string, as specified in linkgit:git-log[1], to be used for
+ the instruction list during an interactive rebase. The format will automatically
+ have the long commit hash prepended to the format.
+
receive.advertiseAtomic::
By default, git-receive-pack will advertise the atomic push
capability to its clients. If you don't want to this capability
Defaults to false. If not set, the value of `transfer.fsckObjects`
is used instead.
+receive.fsck.<msg-id>::
+ When `receive.fsckObjects` is set to true, errors can be switched
+ to warnings and vice versa by configuring the `receive.fsck.<msg-id>`
+ setting where the `<msg-id>` is the fsck message ID and the value
+ is one of `error`, `warn` or `ignore`. For convenience, fsck prefixes
+ the error/warning with the message ID, e.g. "missingEmail: invalid
+ author/committer line - missing email" means that setting
+ `receive.fsck.missingEmail = ignore` will hide that issue.
++
+This feature is intended to support working with legacy repositories
+which would not pass pushing when `receive.fsckObjects = true`, allowing
+the host to accept repositories with certain known issues but still catch
+other issues.
+
+receive.fsck.skipList::
+ The path to a sorted list of object names (i.e. one SHA-1 per
+ line) that are known to be broken in a non-fatal way and should
+ be ignored. This feature is useful when an established project
+ should be accepted despite early commits containing errors that
+ can be safely ignored such as invalid committer email addresses.
+ Note: corrupt objects cannot be skipped with this setting.
+
receive.unpackLimit::
If the number of objects received in a push is below this
limit then the objects will be unpacked into loose object
set when initializing a shared repository.
receive.hideRefs::
- String(s) `receive-pack` uses to decide which refs to omit
- from its initial advertisement. Use more than one
- definitions to specify multiple prefix strings. A ref that
- are under the hierarchies listed on the value of this
- variable is excluded, and is hidden when responding to `git
- push`, and an attempt to update or delete a hidden ref by
- `git push` is rejected.
+ This variable is the same as `transfer.hideRefs`, but applies
+ only to `receive-pack` (and so affects pushes, but not fetches).
+ An attempt to update or delete a hidden ref by `git push` is
+ rejected.
receive.updateServerInfo::
If set to true, git-receive-pack will run git-update-server-info
remote.<name>.receivepack::
The default program to execute on the remote side when pushing. See
- option \--receive-pack of linkgit:git-push[1].
+ option --receive-pack of linkgit:git-push[1].
remote.<name>.uploadpack::
The default program to execute on the remote side when fetching. See
- option \--upload-pack of linkgit:git-fetch-pack[1].
+ option --upload-pack of linkgit:git-fetch-pack[1].
remote.<name>.tagOpt::
- Setting this value to \--no-tags disables automatic tag following when
- fetching from remote <name>. Setting it to \--tags will fetch every
+ Setting this value to --no-tags disables automatic tag following when
+ fetching from remote <name>. Setting it to --tags will fetch every
tag from remote <name>, even if they are not reachable from remote
branch heads. Passing these flags directly to linkgit:git-fetch[1] can
- override this setting. See options \--tags and \--no-tags of
+ override this setting. See options --tags and --no-tags of
linkgit:git-fetch[1].
remote.<name>.vcs::
Defaults to false.
transfer.hideRefs::
- This variable can be used to set both `receive.hideRefs`
- and `uploadpack.hideRefs` at the same time to the same
- values. See entries for these other variables.
+ String(s) `receive-pack` and `upload-pack` use to decide which
+ refs to omit from their initial advertisements. Use more than
+ one definition to specify multiple prefix strings. A ref that is
+ under the hierarchies listed in the value of this variable is
+ excluded, and is hidden when responding to `git push` or `git
+ fetch`. See `receive.hideRefs` and `uploadpack.hideRefs` for
+ program-specific versions of this config.
++
+You may also include a `!` in front of the ref name to negate the entry,
+explicitly exposing it, even if an earlier entry marked it as hidden.
+If you have multiple hideRefs values, later entries override earlier ones
+(and entries in more-specific config files override less-specific ones).
transfer.unpackLimit::
When `fetch.unpackLimit` or `receive.unpackLimit` are
`false`.
uploadpack.hideRefs::
- String(s) `upload-pack` uses to decide which refs to omit
- from its initial advertisement. Use more than one
- definitions to specify multiple prefix strings. A ref that
- are under the hierarchies listed on the value of this
- variable is excluded, and is hidden from `git ls-remote`,
- `git fetch`, etc. An attempt to fetch a hidden ref by `git
- fetch` will fail. See also `uploadpack.allowtipsha1inwant`.
-
-uploadpack.allowtipsha1inwant::
+ This variable is the same as `transfer.hideRefs`, but applies
+ only to `upload-pack` (and so affects only fetches, not pushes).
+ An attempt to fetch a hidden ref by `git fetch` will fail. See
+ also `uploadpack.allowTipSHA1InWant`.
+
+uploadpack.allowTipSHA1InWant::
When `uploadpack.hideRefs` is in effect, allow `upload-pack`
to accept a fetch request that asks for an object at the tip
of a hidden ref (by default, such a request is rejected).
see also `uploadpack.hideRefs`.
+uploadpack.allowReachableSHA1InWant::
+ Allow `upload-pack` to accept a fetch request that asks for an
+ object that is reachable from any ref tip. However, note that
+ calculating object reachability is computationally expensive.
+ Defaults to `false`.
+
uploadpack.keepAlive::
When `upload-pack` has started `pack-objects`, there may be a
quiet period while `pack-objects` prepares the pack. Normally
This option is passed unchanged to gpg's --local-user parameter,
so you may specify a key using any method that gpg supports.
+versionsort.prereleaseSuffix::
+ When version sort is used in linkgit:git-tag[1], prerelease
+ tags (e.g. "1.0-rc1") may appear after the main release
+ "1.0". By specifying the suffix "-rc" in this variable,
+ "1.0-rc1" will appear before "1.0".
++
+This variable can be specified multiple times, once per suffix. The
+order of suffixes in the config file determines the sorting order
+(e.g. if "-pre" appears before "-rc" in the config file then 1.0-preXX
+is sorted before 1.0-rcXX). The sorting order between different
+suffixes is undefined if they are in multiple config files.
+
web.browser::
Specify a web browser that may be used by some commands.
Currently only linkgit:git-instaweb[1] and linkgit:git-help[1]