Merge tag 'v2.13.5' into maint
[gitweb.git] / Documentation / config.txt
index f4721a048b4c413767c0f069d07005c8948244dd..d5c9c4cab60531d178d5c11d623a5c3f1036a0d0 100644 (file)
@@ -79,18 +79,84 @@ escape sequences) are invalid.
 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
 ~~~~~~~
@@ -116,9 +182,26 @@ 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
 ~~~~~~
@@ -150,27 +233,37 @@ integer::
        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.
+       The value for a variable that takes a color is a list of
+       colors (at most two, one for foreground and one for background)
+       and attributes (as many as you want), separated by spaces.
++
+The basic colors accepted are `normal`, `black`, `red`, `green`, `yellow`,
+`blue`, `magenta`, `cyan` and `white`.  The first color given is the
+foreground; the second is the background.
++
+Colors 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 accepted attributes are `bold`, `dim`, `ul`, `blink`, `reverse`,
+`italic`, and `strike` (for crossed-out or "strikethrough" letters).
+The position of any attributes with respect to the colors
+(before, after, or in between), doesn't matter. Specific attributes may
+be turned off by prefixing them with `no` or `no-` (e.g., `noreverse`,
+`no-ul`, etc).
++
+An empty color string produces no color effect at all. This can be used
+to avoid coloring specific elements without disabling color entirely.
++
+For git's pre-defined color slots, 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.
+However, custom log formats may do more complicated and layered
+coloring, and the negated forms may be useful there.
 
 pathname::
        A variable that takes a pathname value can be given a
@@ -255,6 +348,9 @@ advice.*::
        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::
@@ -262,7 +358,7 @@ 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
@@ -324,6 +420,10 @@ core.trustctime::
        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
@@ -340,16 +440,19 @@ core.checkStat::
        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
@@ -441,6 +544,13 @@ 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.
 
+core.sshCommand::
+       If this variable is set, `git fetch` and `git push` will
+       use the specified command instead of `ssh` when they need to
+       connect to a remote system. The command is in the same form as
+       the `GIT_SSH_COMMAND` environment variable and is overridden
+       when the environment variable is set.
+
 core.ignoreStat::
        If true, Git will avoid using lstat() calls to detect if files have
        changed by setting the "assume-unchanged" bit for those tracked files
@@ -503,10 +613,12 @@ core.logAllRefUpdates::
        "`$GIT_DIR/logs/<ref>`", by appending the new and old
        SHA-1, the date/time and the reason of the update, but
        only when the file exists.  If this configuration
-       variable is set to true, missing "`$GIT_DIR/logs/<ref>`"
+       variable is set to `true`, missing "`$GIT_DIR/logs/<ref>`"
        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.
+       `refs/heads/`), remote refs (i.e. under `refs/remotes/`),
+       note refs (i.e. under `refs/notes/`), and the symbolic ref `HEAD`.
+       If it is set to `always`, then a missing reflog is automatically
+       created for any ref under `refs/`.
 +
 This information can be used to determine what commit
 was the tip of a branch "2 days ago".
@@ -574,7 +686,8 @@ core.packedGitLimit::
        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.
 +
@@ -649,13 +762,13 @@ alternative to having an `init.templateDir` where you've changed
 default hooks.
 
 core.editor::
-       Commands such as `commit` and `tag` that lets you edit
-       messages by launching an editor uses the value of this
+       Commands such as `commit` and `tag` that let you edit
+       messages by launching an editor use the value of this
        variable when it is set, and the environment variable
        `GIT_EDITOR` is not set.  See linkgit:git-var[1].
 
 core.commentChar::
-       Commands such as `commit` and `tag` that lets you edit
+       Commands such as `commit` and `tag` that let you edit
        messages consider a line that begins with this character
        commented, and removes them after the editor returns
        (default '#').
@@ -769,10 +882,12 @@ core.sparseCheckout::
        linkgit:git-read-tree[1] for more information.
 
 core.abbrev::
-       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
-       time.
+       Set the length object names are abbreviated to.  If
+       unspecified or set to "auto", an appropriate value is
+       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)::
@@ -939,7 +1054,8 @@ color.branch::
        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
-       only when the output is to a terminal. Defaults to false.
+       only when the output is to a terminal. If unset, then the
+       value of `color.ui` is used (`auto` by default).
 
 color.branch.<slot>::
        Use customized color for branch coloration. `<slot>` is one of
@@ -954,7 +1070,8 @@ color.diff::
        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.
+       If unset, then the value of `color.ui` is used (`auto` by
+       default).
 +
 This does not affect linkgit:git-format-patch[1] or the
 'git-diff-{asterisk}' plumbing commands.  Can be overridden on the
@@ -977,7 +1094,8 @@ color.decorate.<slot>::
 color.grep::
        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`.
+       when the output is written to the terminal.  If unset, then the
+       value of `color.ui` is used (`auto` by default).
 
 color.grep.<slot>::
        Use customized color for grep colorization.  `<slot>` specifies which
@@ -1010,7 +1128,8 @@ color.interactive::
        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.
+       to the terminal. If unset, then the value of `color.ui` is
+       used (`auto` by default).
 
 color.interactive.<slot>::
        Use customized color for 'git add --interactive' and 'git clean
@@ -1026,13 +1145,15 @@ color.showBranch::
        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.
+       only when the output is to a terminal. If unset, then the
+       value of `color.ui` is used (`auto` by default).
 
 color.status::
        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
-       only when the output is to a terminal. Defaults to false.
+       only when the output is to a terminal. If unset, then the
+       value of `color.ui` is used (`auto` by default).
 
 color.status.<slot>::
        Use customized color for status colorization. `<slot>` is
@@ -1042,7 +1163,10 @@ color.status.<slot>::
        `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::
@@ -1187,6 +1311,15 @@ difftool.<tool>.cmd::
 difftool.prompt::
        Prompt before each invocation of the diff tool.
 
+fastimport.unpackLimit::
+       If the number of objects imported by linkgit:git-fast-import[1]
+       is below this limit, then the objects will be unpacked into
+       loose object files.  However if the number of imported objects
+       equals or exceeds this limit then the pack will be stored as a
+       pack.  Storing the pack from a fast-import can make the import
+       operation complete faster, especially on slow filesystems.  If
+       not set, the value of `transfer.unpackLimit` is used instead.
+
 fetch.recurseSubmodules::
        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
@@ -1218,6 +1351,11 @@ fetch.prune::
        If true, fetch will automatically behave as if the `--prune`
        option was given on the command line.  See also `remote.<name>.prune`.
 
+fetch.output::
+       Control how ref update status is printed. Valid values are
+       `full` and `compact`. Default value is `full`. See section
+       OUTPUT in linkgit:git-fetch[1] for detail.
+
 format.attach::
        Enable multipart/mixed attachments as the default for
        'format-patch'.  The value can also be a double quoted string
@@ -1225,6 +1363,16 @@ format.attach::
        value as the boundary.  See the --attach option in
        linkgit:git-format-patch[1].
 
+format.from::
+       Provides the default value for the `--from` option to format-patch.
+       Accepts a boolean value, or a name and email address.  If false,
+       format-patch defaults to `--no-from`, using commit authors directly in
+       the "From:" field of patch mails.  If true, format-patch defaults to
+       `--from`, using your committer identity in the "From:" field of patch
+       mails and including a "From:" field in the body of the patch mail if
+       different.  If set to a non-boolean value, format-patch uses that
+       value instead of your committer identity.  Defaults to false.
+
 format.numbered::
        A boolean which can enable or disable sequence numbers in patch
        subjects.  It defaults to "auto" which enables it only if there
@@ -1328,7 +1476,7 @@ fsck.skipList::
 gc.aggressiveDepth::
        The depth parameter used in the delta compression
        algorithm used by 'git gc --aggressive'.  This defaults
-       to 250.
+       to 50.
 
 gc.aggressiveWindow::
        The window size parameter used in the delta compression
@@ -1352,6 +1500,12 @@ gc.autoDetach::
        Make `git gc --auto` return immediately and run in background
        if the system supports it. Default is true.
 
+gc.logExpiry::
+       If the file gc.log exists, then `git gc --auto` won't run
+       unless that file is more than 'gc.logExpiry' old.  Default is
+       "1.day".  See `gc.pruneExpire` for more ways to specify its
+       value.
+
 gc.packRefs::
        Running `git pack-refs` in a repository renders it
        unclonable by Git versions prior to 1.5.1.2 over dumb
@@ -1365,7 +1519,9 @@ gc.pruneExpire::
        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, or "never" may be used to
-       suppress pruning.
+       suppress pruning.  This feature helps prevent corruption when
+       'git gc' runs concurrently with another process writing to the
+       repository; see the "NOTES" section of linkgit:git-gc[1].
 
 gc.worktreePruneExpire::
        When 'git gc' is run, it calls
@@ -1692,6 +1848,20 @@ http.emptyAuth::
        a username in the URL, as libcurl normally requires a username for
        authentication.
 
+http.delegation::
+       Control GSSAPI credential delegation. The delegation is disabled
+       by default in libcurl since version 7.21.7. Set parameter to tell
+       the server what it is allowed to delegate when it comes to user
+       credentials. Used with GSS/kerberos. Possible values are:
++
+--
+* `none` - Don't allow any delegation.
+* `policy` - Delegates if and only if the OK-AS-DELEGATE flag is set in the
+  Kerberos service ticket, which is a matter of realm policy.
+* `always` - Unconditionally allow the server to delegate.
+--
+
+
 http.extraHeader::
        Pass an additional HTTP header when communicating with a server.  If
        more than one such entry exists, all of them are added as extra
@@ -1833,6 +2003,16 @@ http.userAgent::
        of common USER_AGENT strings (but not including those like git/1.7.1).
        Can be overridden by the `GIT_HTTP_USER_AGENT` environment variable.
 
+http.followRedirects::
+       Whether git should follow HTTP redirects. If set to `true`, git
+       will transparently follow any redirect issued by a server it
+       encounters. If set to `false`, git will treat all redirects as
+       errors. If set to `initial`, git will follow redirects only for
+       the initial request to a remote, but not for subsequent
+       follow-up HTTP requests. Since git uses the redirected URL as
+       the base for the follow-up requests, this is generally
+       sufficient. The default is `initial`.
+
 http.<url>.*::
        Any of the http.* options above can be applied selectively to some URLs.
        For a config key to match a URL, each element of the config key is
@@ -1843,7 +2023,10 @@ http.<url>.*::
   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.
@@ -1878,6 +2061,17 @@ Environment variable settings always override any matches.  The URLs that are
 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
@@ -1965,12 +2159,20 @@ log.follow::
        i.e. it cannot be used to follow multiple files and does not work well
        on non-linear history.
 
+log.graphColors::
+       A list of colors, separated by commas, that can be used to draw
+       history lines in `git log --graph`.
+
 log.showRoot::
        If true, the initial commit will be shown as a big creation event.
        This is equivalent to a diff against an empty tree.
        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`.
@@ -2250,6 +2452,52 @@ pretty.<name>::
        Note that an alias with the same name as a built-in format
        will be silently ignored.
 
+protocol.allow::
+       If set, provide a user defined default policy for all protocols which
+       don't explicitly have a policy (`protocol.<name>.allow`).  By default,
+       if unset, known-safe protocols (http, https, git, ssh, file) have a
+       default policy of `always`, known-dangerous protocols (ext) have a
+       default policy of `never`, and all other protocols have a default
+       policy of `user`.  Supported policies:
++
+--
+
+* `always` - protocol is always able to be used.
+
+* `never` - protocol is never able to be used.
+
+* `user` - protocol is only able to be used when `GIT_PROTOCOL_FROM_USER` is
+  either unset or has a value of 1.  This policy should be used when you want a
+  protocol to be directly usable by the user but don't want it used by commands which
+  execute clone/fetch/push commands without user input, e.g. recursive
+  submodule initialization.
+
+--
+
+protocol.<name>.allow::
+       Set a policy to be used by protocol `<name>` with clone/fetch/push
+       commands. See `protocol.allow` above for the available policies.
++
+The protocol names currently used by git are:
++
+--
+  - `file`: any local file-based path (including `file://` URLs,
+    or local paths)
+
+  - `git`: the anonymous git protocol over a direct TCP
+    connection (or proxy, if configured)
+
+  - `ssh`: git over ssh (including `host:path` syntax,
+    `ssh://`, etc).
+
+  - `http`: git over http, both "smart http" and "dumb http".
+    Note that this does _not_ include `https`; if you want to configure
+    both, you must do so individually.
+
+  - any external helpers are named by their protocol (e.g., use
+    `hg` to allow the `git-remote-hg` helper)
+--
+
 pull.ff::
        By default, Git does not create an extra merge commit when merging
        a commit that is a descendant of the current commit. Instead, the
@@ -2306,6 +2554,8 @@ push.default::
   pushing to the same repository you would normally pull from
   (i.e. central workflow).
 
+* `tracking` - This is a deprecated synonym for `upstream`.
+
 * `simple` - in centralized workflow, work like `upstream` with an
   added safety to refuse to push if the upstream branch's name is
   different from the local one.
@@ -2374,7 +2624,7 @@ rebase.autoSquash::
        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
@@ -2392,15 +2642,19 @@ rebase.missingCommitsCheck::
        command in the todo-list.
        Defaults to "ignore".
 
-rebase.instructionFormat
+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
-       to be advertised, set this variable to false.
+       capability to its clients. If you don't want to advertise this
+       capability, set this variable to false.
+
+receive.advertisePushOptions::
+       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
@@ -2455,6 +2709,15 @@ receive.fsck.skipList::
        can be safely ignored such as invalid committer email addresses.
        Note: corrupt objects cannot be skipped with this setting.
 
+receive.keepAlive::
+       After receiving the pack from the client, `receive-pack` may
+       produce no output (if `--quiet` was specified) while processing
+       the pack, causing some networks to drop the TCP connection.
+       With this option set, if `receive-pack` does not transmit
+       any data in this phase for `receive.keepAlive` seconds, it will
+       send a short keepalive packet.  The default is 5 seconds; set
+       to 0 to disable keepalives entirely.
+
 receive.unpackLimit::
        If the number of objects received in a push is below this
        limit then the objects will be unpacked into loose object
@@ -2465,6 +2728,12 @@ receive.unpackLimit::
        especially on slow filesystems.  If not set, the value of
        `transfer.unpackLimit` is used instead.
 
+receive.maxInputSize::
+       If the size of the incoming pack stream is larger than this
+       limit, then git-receive-pack will error out, instead of
+       accepting the pack file. If not set or set to 0, then the size
+       is unlimited.
+
 receive.denyDeletes::
        If set to true, git-receive-pack will deny a ref update that deletes
        the ref. Use this to prevent such a ref deletion via a push.
@@ -2677,10 +2946,45 @@ sendemail.xmailer::
 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
@@ -2702,6 +3006,11 @@ status.displayCommentPrefix::
        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
@@ -2739,20 +3048,22 @@ status.submoduleSummary::
 
 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>.path::
 submodule.<name>.url::
-       The path within this project and URL for a submodule. These
-       variables are initially populated by 'git submodule init'. See
-       linkgit:git-submodule[1] and linkgit:gitmodules[5] for
-       details.
+       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'. 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::
        The default update procedure for a submodule. This variable
@@ -2789,12 +3100,39 @@ submodule.<name>.ignore::
        "--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
        in parallel. A value of 0 will give some reasonable default.
        If unset, it defaults to 1.
 
+submodule.alternateLocation::
+       Specifies how the submodules obtain alternates when submodules are
+       cloned. Possible values are `no`, `superproject`.
+       By default `no` is assumed, which doesn't add references. When the
+       value is set to `superproject` the submodule to be cloned computes
+       its alternates location relative to the superprojects alternate.
+
+submodule.alternateErrorStrategy::
+       Specifies how to treat errors with the alternates for a submodule
+       as computed via `submodule.alternateLocation`. Possible values are
+       `ignore`, `info`, `die`. Default is `die`.
+
 tag.forceSignAnnotated::
        A boolean to specify whether annotated tags created should be GPG signed.
        If `--annotate` is specified on the command line, it takes
@@ -2839,6 +3177,11 @@ is omitted from the advertisements but `refs/heads/master` and
 `refs/namespaces/bar/refs/heads/master` are still advertised as so-called
 "have" lines. In order to match refs before stripping, add a `^` in front of
 the ref name. If you combine `!` and `^`, `!` must be specified first.
++
+Even if you hide refs, a client may still be able to steal the target
+objects via the techniques described in the "SECURITY" section of the
+linkgit:gitnamespaces[7] man page; it's best to keep private data in a
+separate repository.
 
 transfer.unpackLimit::
        When `fetch.unpackLimit` or `receive.unpackLimit` are
@@ -2848,7 +3191,7 @@ transfer.unpackLimit::
 uploadarchive.allowUnreachable::
        If true, allow clients to use `git archive --remote` to request
        any tree, whether reachable from the ref tips or not. See the
-       discussion in the `SECURITY` section of
+       discussion in the "SECURITY" section of
        linkgit:git-upload-archive[1] for more details. Defaults to
        `false`.
 
@@ -2862,12 +3205,23 @@ 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`.
+       See also `uploadpack.hideRefs`.  Even if this is false, a client
+       may be able to steal objects via the techniques described in the
+       "SECURITY" section of the linkgit:gitnamespaces[7] man page; it's
+       best to keep private data in a separate repository.
 
 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`.  Even if this is false, a client may be able
+       to steal objects via the techniques described in the "SECURITY"
+       section of the linkgit:gitnamespaces[7] man page; it's best to
+       keep private data in a separate repository.
+
+uploadpack.allowAnySHA1InWant::
+       Allow `upload-pack` to accept a fetch request that asks for any
+       object at all.
        Defaults to `false`.
 
 uploadpack.keepAlive::
@@ -2881,6 +3235,21 @@ uploadpack.keepAlive::
        `uploadpack.keepAlive` seconds. Setting this option to 0
        disables keepalive packets entirely. The default is 5 seconds.
 
+uploadpack.packObjectsHook::
+       If this option is set, when `upload-pack` would run
+       `git pack-objects` to create a packfile for a client, it will
+       run this shell command instead.  The `pack-objects` command and
+       arguments it _would_ have run (including the `git pack-objects`
+       at the beginning) are appended to the shell command. The stdin
+       and stdout of the hook are treated as if `pack-objects` itself
+       was run. I.e., `upload-pack` will feed input intended for
+       `pack-objects` to the hook, and expects a completed packfile on
+       stdout.
++
+Note that this configuration variable is ignored if it is seen in the
+repository-level config (this is a safety measure against fetching from
+untrusted repositories).
+
 url.<base>.insteadOf::
        Any URL that starts with this value will be rewritten to
        start, instead, with <base>. In cases where some site serves a
@@ -2891,6 +3260,13 @@ url.<base>.insteadOf::
        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;
@@ -2932,17 +3308,39 @@ user.signingKey::
        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.
+versionsort.prereleaseSuffix (deprecated)::
+       Deprecated alias for `versionsort.suffix`.  Ignored if
+       `versionsort.suffix` is set.
+
+versionsort.suffix::
+       Even when version sort is used in linkgit:git-tag[1], tagnames
+       with the same base version but different suffixes are still sorted
+       lexicographically, resulting e.g. in prerelease tags appearing
+       after the main release (e.g. "1.0-rc1" after "1.0").  This
+       variable can be specified to determine the sorting order of tags
+       with different suffixes.
++
+By specifying a single suffix in this variable, any tagname containing
+that suffix will appear before the corresponding main release.  E.g. if
+the variable is set to "-rc", then all "1.0-rcX" tags will appear before
+"1.0".  If specified multiple times, once per suffix, then the order of
+suffixes in the configuration will determine the sorting order of tagnames
+with those suffixes.  E.g. if "-pre" appears before "-rc" in the
+configuration, then all "1.0-preX" tags will be listed before any
+"1.0-rcX" tags.  The placement of the main release tag relative to tags
+with various suffixes can be determined by specifying the empty suffix
+among those other suffixes.  E.g. if the suffixes "-rc", "", "-ck" and
+"-bfs" appear in the configuration in this order, then all "v4.8-rcX" tags
+are listed first, followed by "v4.8", then "v4.8-ckX" and finally
+"v4.8-bfsX".
++
+If more than one suffixes match the same tagname, then that tagname will
+be sorted according to the suffix which starts at the earliest position in
+the tagname.  If more than one different matching suffixes start at
+that earliest position, then that tagname will be sorted according to the
+longest of those suffixes.
+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.