Includes
~~~~~~~~
-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
-variable takes a pathname as its value, and is subject to tilde
-expansion.
+The `include` and `includeIf` sections allow you to include config
+directives from another source. These sections behave identically to
+each other with the exception that `includeIf` sections may be ignored
+if their condition does not evaluate to true; see "Conditional includes"
+below.
-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
-found. See below for examples.
+You can include a config file from another by setting the special
+`include.path` (or `includeIf.*.path`) variable to the name of the file
+to be included. The variable takes a pathname as its value, and is
+subject to tilde expansion. These variables can be given multiple times.
+The contents of the included file are inserted immediately, as if they
+had been found at the location of the include directive. If the value of the
+variable is a relative path, the path is considered to
+be relative to the configuration file in which the include directive
+was found. See below for examples.
+
+Conditional includes
+~~~~~~~~~~~~~~~~~~~~
+
+You can include a config file from another conditionally by setting a
+`includeIf.<condition>.path` variable to the name of the file to be
+included.
+
+The condition starts with a keyword followed by a colon and some data
+whose format and meaning depends on the keyword. Supported keywords
+are:
+
+`gitdir`::
+
+ The data that follows the keyword `gitdir:` is used as a glob
+ pattern. If the location of the .git directory matches the
+ pattern, the include condition is met.
++
+The .git location may be auto-discovered, or come from `$GIT_DIR`
+environment variable. If the repository is auto discovered via a .git
+file (e.g. from submodules, or a linked worktree), the .git location
+would be the final location where the .git directory is, not where the
+.git file is.
++
+The pattern can contain standard globbing wildcards and two additional
+ones, `**/` and `/**`, that can match multiple path components. Please
+refer to linkgit:gitignore[5] for details. For convenience:
+
+ * If the pattern starts with `~/`, `~` will be substituted with the
+ content of the environment variable `HOME`.
+
+ * If the pattern starts with `./`, it is replaced with the directory
+ containing the current config file.
+
+ * If the pattern does not start with either `~/`, `./` or `/`, `**/`
+ will be automatically prepended. For example, the pattern `foo/bar`
+ becomes `**/foo/bar` and would match `/any/path/to/foo/bar`.
+
+ * If the pattern ends with `/`, `**` will be automatically added. For
+ example, the pattern `foo/` becomes `foo/**`. In other words, it
+ matches "foo" and everything inside, recursively.
+
+`gitdir/i`::
+ This is the same as `gitdir` except that matching is done
+ case-insensitively (e.g. on case-insensitive file sytems)
+
+A few more notes on matching via `gitdir` and `gitdir/i`:
+
+ * Symlinks in `$GIT_DIR` are not resolved before matching.
+
+ * Both the symlink & realpath versions of paths will be matched
+ outside of `$GIT_DIR`. E.g. if ~/git is a symlink to
+ /mnt/storage/git, both `gitdir:~/git` and `gitdir:/mnt/storage/git`
+ will match.
++
+This was not the case in the initial release of this feature in
+v2.13.0, which only matched the realpath version. Configuration that
+wants to be compatible with the initial release of this feature needs
+to either specify only the realpath version, or both versions.
+
+ * Note that "../" is not special and will match literally, which is
+ unlikely what you want.
Example
~~~~~~~
[include]
path = /path/to/foo.inc ; include by absolute path
- path = foo ; expand "foo" relative to the current file
- path = ~/foo ; expand "foo" in your `$HOME` directory
+ path = foo.inc ; find "foo.inc" relative to the current file
+ path = ~/foo.inc ; find "foo.inc" in your `$HOME` directory
+
+ ; include if $GIT_DIR is /path/to/foo/.git
+ [includeIf "gitdir:/path/to/foo/.git"]
+ path = /path/to/foo.inc
+
+ ; include for all repositories inside /path/to/group
+ [includeIf "gitdir:/path/to/group/"]
+ path = /path/to/foo.inc
+
+ ; include for all repositories inside $HOME/to/group
+ [includeIf "gitdir:~/to/group/"]
+ path = /path/to/foo.inc
+ ; relative paths are always relative to the including
+ ; file (if the condition is true); their location is not
+ ; affected by the condition
+ [includeIf "gitdir:/path/to/group/"]
+ path = foo.inc
Values
~~~~~~
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>`
+ true;; Boolean true literals are `yes`, `on`, `true`,
+ and `1`. Also, a variable defined without `= <value>`
is taken as true.
- false;; Boolean false can be spelled as `no`, `off`,
- `false`, or `0`.
+ false;; Boolean false literals are `no`, `off`, `false`,
+ `0` and the empty string.
+
When converting value to the canonical form using `--bool` type
-specifier; 'git config' will ensure that the output is "true" or
+specifier, 'git config' will ensure that the output is "true" or
"false" (spelled in lowercase).
integer::
rmHints::
In case of failure in the output of linkgit:git-rm[1],
show directions on how to proceed from the current state.
+ addEmbeddedRepo::
+ Advice on what to do when you've accidentally added one
+ git repo inside of another.
--
core.fileMode::
is to be honored.
+
Some filesystems lose the executable bit when a file that is
-marked as executable is checked out, or checks out an
+marked as executable is checked out, or checks out a
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
crawlers and some backup systems).
See linkgit:git-update-index[1]. True by default.
+core.splitIndex::
+ If true, the split-index feature of the index will be used.
+ See linkgit:git-update-index[1]. False by default.
+
core.untrackedCache::
Determines what to do about the untracked cache feature of the
index. It will be kept, if this variable is unset or set to
all fields, including the sub-second part of mtime and ctime.
core.quotePath::
- The commands that output paths (e.g. 'ls-files',
- 'diff'), when not given the `-z` option, will quote
- "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
- variable.
+ Commands that output paths (e.g. 'ls-files', 'diff'), will
+ quote "unusual" characters in the pathname by enclosing the
+ pathname in double-quotes and escaping those characters with
+ backslashes in the same way C escapes control characters (e.g.
+ `\t` for TAB, `\n` for LF, `\\` for backslash) or bytes with
+ values larger than 0x80 (e.g. octal `\302\265` for "micro" in
+ UTF-8). If this variable is set to false, bytes higher than
+ 0x80 are not considered "unusual" any more. Double-quotes,
+ backslash and control characters are always escaped regardless
+ of the setting of this variable. A simple space character is
+ not considered "unusual". Many commands can output pathnames
+ completely verbatim using the `-z` option. The default value
+ is true.
core.eol::
Sets the line ending type to use in the working directory for
bytes at once to complete an operation it will unmap existing
regions to reclaim virtual address space within the process.
+
-Default is 256 MiB on 32 bit platforms and 8 GiB on 64 bit platforms.
+Default is 256 MiB on 32 bit platforms and 32 TiB (effectively
+unlimited) 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.
+
computed based on the approximate number of packed objects
in your repository, which hopefully is enough for
abbreviated object names to stay unique for some time.
+ The minimum length is 4.
add.ignoreErrors::
add.ignore-errors (deprecated)::
`untracked` (files which are not tracked by Git),
`branch` (the current branch),
`nobranch` (the color the 'no branch' warning is shown in, defaulting
- to red), or
+ to red),
+ `localBranch` or `remoteBranch` (the local and remote branch names,
+ respectively, when branch and tracking information is displayed in the
+ status short-format), or
`unmerged` (files which have unmerged changes).
color.ui::
must match exactly between the config key and the URL.
. Host/domain name (e.g., `example.com` in `https://example.com/`).
- This field must match exactly between the config key and the URL.
+ This field must match between the config key and the URL. It is
+ possible to specify a `*` as part of the host name to match all subdomains
+ at this level. `https://*.example.com/` for example would match
+ `https://foo.example.com/`, but not `https://foo.bar.example.com/`.
. Port number (e.g., `8080` in `http://example.com:8080/`).
This field must match exactly between the config key and the URL.
matched against are those given directly to Git commands. This means any URLs
visited as a result of a redirection do not participate in matching.
+ssh.variant::
+ Depending on the value of the environment variables `GIT_SSH` or
+ `GIT_SSH_COMMAND`, or the config setting `core.sshCommand`, Git
+ auto-detects whether to adjust its command-line parameters for use
+ with plink or tortoiseplink, as opposed to the default (OpenSSH).
++
+The config variable `ssh.variant` can be set to override this auto-detection;
+valid values are `ssh`, `plink`, `putty` or `tortoiseplink`. Any other value
+will be treated as normal ssh. This setting can be overridden via the
+environment variable `GIT_SSH_VARIANT`.
+
i18n.commitEncoding::
Character encoding the commit messages are stored in; Git itself
does not care per se, but this information is necessary e.g. when
Tools like linkgit:git-log[1] or linkgit:git-whatchanged[1], which
normally hide the root commit will now show it. True by default.
+log.showSignature::
+ If true, makes linkgit:git-log[1], linkgit:git-show[1], and
+ linkgit:git-whatchanged[1] assume `--show-signature`.
+
log.mailmap::
If true, makes linkgit:git-log[1], linkgit:git-show[1], and
linkgit:git-whatchanged[1] assume `--use-mailmap`.
If set to true enable `--autosquash` option by default.
rebase.autoStash::
- When set to true, automatically create a temporary stash
+ When set to true, automatically create a temporary stash entry
before the operation begins, and apply it after the operation
ends. This means that you can run rebase on a dirty worktree.
However, use with care: the final stash application after a
capability, set this variable to false.
receive.advertisePushOptions::
- By default, git-receive-pack will advertise the push options
- capability to its clients. If you don't want to advertise this
- capability, set this variable to false.
+ When set to true, git-receive-pack will advertise the push options
+ capability to its clients. False by default.
receive.autogc::
By default, git-receive-pack will run "git-gc --auto" after
sendemail.<identity>.*::
Identity-specific versions of the 'sendemail.*' parameters
- found below, taking precedence over those when the this
- identity is selected, through command-line or
+ found below, taking precedence over those when this
+ identity is selected, through either the command-line or
`sendemail.identity`.
sendemail.aliasesFile::
sendemail.signedoffcc (deprecated)::
Deprecated alias for `sendemail.signedoffbycc`.
+sendemail.smtpBatchSize::
+ Number of messages to be sent per connection, after that a relogin
+ will happen. If the value is 0 or undefined, send all messages in
+ one connection.
+ See also the `--batch-size` option of linkgit:git-send-email[1].
+
+sendemail.smtpReloginDelay::
+ Seconds wait before reconnecting to smtp server.
+ See also the `--relogin-delay` option of linkgit:git-send-email[1].
+
showbranch.default::
The default set of branches for linkgit:git-show-branch[1].
See linkgit:git-show-branch[1].
+splitIndex.maxPercentChange::
+ When the split index feature is used, this specifies the
+ percent of entries the split index can contain compared to the
+ total number of entries in both the split index and the shared
+ index before a new shared index is written.
+ The value should be between 0 and 100. If the value is 0 then
+ a new shared index is always written, if it is 100 a new
+ shared index is never written.
+ By default the value is 20, so a new shared index is written
+ if the number of entries in the split index would be greater
+ than 20 percent of the total number of entries.
+ See linkgit:git-update-index[1].
+
+splitIndex.sharedIndexExpire::
+ When the split index feature is used, shared index files that
+ were not modified since the time this variable specifies will
+ be removed when a new shared index file is created. The value
+ "now" expires all entries immediately, and "never" suppresses
+ expiration altogether.
+ The default value is "2.weeks.ago".
+ Note that a shared index file is considered modified (for the
+ purpose of expiration) each time a new split-index file is
+ either created based on it or read from it.
+ See linkgit:git-update-index[1].
+
status.relativePaths::
By default, linkgit:git-status[1] shows paths relative to the
current directory. Setting this variable to `false` shows paths
behavior of linkgit:git-status[1] in Git 1.8.4 and previous.
Defaults to false.
+status.showStash::
+ If set to true, linkgit:git-status[1] will display the number of
+ entries currently stashed away.
+ Defaults to false.
+
status.showUntrackedFiles::
By default, linkgit:git-status[1] and linkgit:git-commit[1] show
files which are not currently tracked by Git. Directories which
stash.showPatch::
If this is set to true, the `git stash show` command without an
- option will show the stash in patch form. Defaults to false.
+ option will show the stash entry in patch form. Defaults to false.
See description of 'show' command in linkgit:git-stash[1].
stash.showStat::
If this is set to true, the `git stash show` command without an
- option will show diffstat of the stash. Defaults to true.
+ option will show diffstat of the stash entry. Defaults to true.
See description of 'show' command in linkgit:git-stash[1].
submodule.<name>.url::
The URL for a submodule. This variable is copied from the .gitmodules
file to the git config via 'git submodule init'. The user can change
the configured URL before obtaining the submodule via 'git submodule
- update'. After obtaining the submodule, the presence of this variable
- is used as a sign whether the submodule is of interest to git commands.
+ update'. If neither submodule.<name>.active or submodule.active are
+ set, the presence of this variable is used as a fallback to indicate
+ whether the submodule is of interest to git commands.
See linkgit:git-submodule[1] and linkgit:gitmodules[5] for details.
submodule.<name>.update::
"--ignore-submodules" option. The 'git submodule' commands are not
affected by this setting.
+submodule.<name>.active::
+ Boolean value indicating if the submodule is of interest to git
+ commands. This config option takes precedence over the
+ submodule.active config option.
+
+submodule.active::
+ A repeated field which contains a pathspec used to match against a
+ submodule's path to determine if the submodule is of interest to git
+ commands.
+
+submodule.recurse::
+ Specifies if commands recurse into submodules by default. This
+ applies to all commands that have a `--recurse-submodules` option.
+ Defaults to false.
+
submodule.fetchJobs::
Specifies how many submodules are fetched/cloned at the same time.
A positive integer allows up to that number of submodules fetched
the best alternative for the particular user, even for a
never-before-seen repository on the site. When more than one
insteadOf strings match a given URL, the longest match is used.
++
+Note that any protocol restrictions will be applied to the rewritten
+URL. If the rewrite changes the URL to use a custom protocol or remote
+helper, you may need to adjust the `protocol.*.allow` config to permit
+the request. In particular, protocols you expect to use for submodules
+must be set to `always` rather than the default of `user`. See the
+description of `protocol.allow` above.
url.<base>.pushInsteadOf::
Any URL that starts with this value will not be pushed to;